feat(python): Update docs for SDK 2.0 (#9182)

docs/platforms/python/configuration/options.mdx

@@ -165,22 +165,6 @@ A path to an alternative CA bundle file in PEM-format.
 
 </ConfigKey>
 
-<ConfigKey name="request-bodies">
-
-#### Deprecated
-
-Has been renamed to [max_request_body_size](/platforms/python/configuration/options/#max-request-body-size).
-
-</ConfigKey>
-
-<ConfigKey name="with-locals">
-
-#### Deprecated
-
-Has been renamed to [include_local_variables](/platforms/python/configuration/options/#include-local-variables).
-
-</ConfigKey>
-
 <ConfigKey name="send-client-reports">
 
 Set this boolean to `false` to disable sending of client reports. Client reports are a protocol feature that let clients send status reports about themselves to Sentry. They are currently mainly used to emit outcomes for events that were never sent.

docs/platforms/python/enriching-events/scopes/index.mdx

@@ -1,59 +1,37 @@
 ---
-title: Scopes and Hubs
+title: Scopes
 description: "SDKs will typically automatically manage the scopes for you in the framework integrations. Learn what a scope is and how you can use it to your advantage."
 ---
 
-When an event is captured and sent to Sentry, SDKs will merge that event data with extra
-information from the current scope. SDKs will typically automatically manage the scopes
-for you in the framework integrations and you don't need to think about them. However,
-you should know what a scope is and how you can use it for your advantage.
+Scopes store extra data that the SDK adds to your event when sending the event to Sentry. While the SDKs typically manage the scope automatically, understanding how scopes work and how you can manage them manually can be helpful.
 
-## What's a Scope, What's a Hub
+## What is a Scope?
 
-You can think of the hub as the central point that our SDKs use to route an
-event to Sentry. When you call `init()` a hub is created and a client and a
-blank scope are created on it. That hub is then associated with the current
-thread and will internally hold a stack of scopes.
+A scope manages an event's data. For instance, the SDK stores [contexts](../context/) and [breadcrumbs](../breadcrumbs/) on the scope.
 
-The scope will hold useful information that should be sent along with the
-event. For instance [contexts](../context/) or
-[breadcrumbs](../breadcrumbs/) are stored on
-the scope. When a scope is pushed, it inherits all data from the parent scope
-and when it pops all modifications are reverted.
+There are three types of scopes. Exactly one scope of each type will be active at a specific point in time.
 
-The default SDK integrations will push and pop scopes intelligently. For
-instance web framework integrations will create and destroy scopes around your
-routes or controllers.
+- *Global scope*: A single globally-shared scope storing data relevant for the whole app (such as the release).
+- *Isolation scope*: Thread-local scope created for each request-response lifecycle to store data relevant to the request.
+- *Current scope*: Thread-local scope created for each span to store data relevant to the span.
 
-## How the Scope and Hub Work
+The SDK and the SDK's built-in integrations automatically manage the scopes. For example, web framework integrations create an isolation scope for each request handled. When you call a top-level API function, such as <PlatformIdentifier name="set-tag" />, the SDK determines the correct scope on which to operate.
 
-As you start using an SDK, a scope and hub are automatically created for you out
-of the box. It's unlikely that you'll interact with the hub directly unless you're
-writing an integration or you want to create or destroy scopes. Scopes, on the
-other hand are more user facing. You can call <PlatformIdentifier name="configure-scope" /> at any point in
-time to modify data stored on the scope. This is useful for doing things like
-[modifying the context](../context/).
+When sending an event to Sentry, the final data applied to the event is the result of merging the three scopes, applying data from each in turn. The global scope is applied first, followed by the isolation scope, and then the current scope.
 
-<Alert>
-If you are very curious about how thread locality works: On platforms such as .NET
-or on Python 3.7 and later we will use "ambient data" to have either the hub flow
-with your code or the hub is already a singleton that internally manages the scope.
+## Changing the Scope
 
-Effectively this means that when you spawn a task in .NET and the execution flow is
-not suppressed all the context you have bound to the scope in Sentry will flow along.
-If however you suppress the flow, you get new scope data.
+We generally recommend using the top-level API to manage your scopes, since the SDK's automatic scope management handles most use cases.
 
-</Alert>
+However, if your use case requires direct access to the scope object, you can use the <PlatformIdentifier name="new-scope" /> context manager. <PlatformIdentifier name="new-scope" /> forks the current scope, allows you to modify the new scope while the context manager is active, and restores the original scope afterwards. Using <PlatformIdentifier name="new-scope" /> allows you to send data for only one specific event, such as [modifying the context](../context/). It is roughly equivalent to the <PlatformIdentifier name="push-scope" /> context manager in earlier (1.x) versions of the SDK.
 
-When you call a global function such as <PlatformIdentifier name="capture-event" /> internally Sentry
-discovers the current hub and asks it to capture an event. Internally the hub will
-then merge the event with the topmost scope's data.
+<Note>
 
-## Configuring the Scope
+Avoid calling top-level APIs inside the  <PlatformIdentifier name="new-scope" /> context manager. The top-level API might interact with a different scope from what <PlatformIdentifier name="new-scope" /> yields, causing unintended results. While within the <PlatformIdentifier name="new-scope" /> context manager, please call methods directly on the scope that <PlatformIdentifier name="new-scope" /> yields!
 
-The most useful operation when working with scopes is the <PlatformIdentifier name="configure-scope" /> function. It can be used to reconfigure the current scope.
+</Note>
 
-You can, for instance, add custom tags or inform Sentry about the currently authenticated user.
+Using <PlatformIdentifier name="new-scope" /> allows you to attach additional information, such as adding custom tags or informing Sentry about the currently authenticated user.
 
 <PlatformContent includePath="enriching-events/scopes/configure-scope" />
 
@@ -63,23 +41,3 @@ You can also apply this configuration when unsetting a user at logout:
 
 To learn what useful information can be associated with scopes see
 [the context documentation](../context/).
-
-## Local Scopes
-
-We also support pushing and configuring a scope within a single call. This is typically
-called <PlatformIdentifier name="push-scope" /> or implemented as a function parameter on the capture methods, depending on the SDK. It's very helpful if
-you only want to send data for one specific event.
-
-### Using <PlatformIdentifier name="push-scope" />
-
-In the following example we use <PlatformIdentifier name="push-scope" /> to attach a `level` and a `tag` to only one specific error:
-
-<PlatformContent includePath="enriching-events/scopes/with-scope" />
-
-While this example looks similar to <PlatformIdentifier name="configure-scope" />, it is actually very different.
-Calls to <PlatformIdentifier name="configure-scope" /> change the current active scope; all successive calls to <PlatformIdentifier name="configure-scope" /> will maintain previously set changes unless they are explicitly unset.
-
-On the other hand, <PlatformIdentifier name="push-scope" /> creates a clone of the current scope, and the changes
-made will stay isolated within the <PlatformIdentifier name="push-scope" /> callback function. This allows you to
-more easily isolate pieces of context information to specific locations in your code or
-even call <PlatformIdentifier name="clear" /> to briefly remove all context information.

docs/platforms/python/index.mdx

@@ -19,6 +19,12 @@ Don't already have an account and Sentry project established? Head over to [sent
 
 If you prefer to follow video instructions, see [How to Install the Sentry Python SDK in 60 Seconds](https://vimeo.com/899368672).
 
+<Note>
+
+Version 2.0 of the Sentry Python SDK is now available. If you're looking to upgrade from 1.x, check out the <PlatformLink to="/migration/1.x-to-2.x/">migration guide</PlatformLink>.
+
+</Note>
+
 ## Install
 
 Sentry captures data by using an SDK within your application’s runtime.

docs/platforms/python/integrations/asgi/index.mdx

@@ -79,7 +79,7 @@ Additionally, a transaction will show up in the "Performance" section on [sentry
 
 - Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled.
 
-- The ASGI middleware does not behave like a regular integration. It is not initialized through an extra parameter to `init` and is not attached to a client. When capturing or supplementing events, it just uses the currently active hub.
+- The ASGI middleware does not behave like a regular integration. It is not initialized through an extra parameter to `init` and is not attached to a client. When capturing or supplementing events, it just uses the currently active scopes.
 
 ## Supported Versions
 

docs/platforms/python/integrations/boto3/index.mdx

@@ -31,4 +31,6 @@ sentry_sdk.init(
 ## Supported Versions
 
 - botocore: 1.12+
-- Python: 2.7+
+- Python: 3.6+
+
+<Include name="python-use-older-sdk-for-legacy-support.mdx" />

docs/platforms/python/integrations/bottle/index.mdx

@@ -106,4 +106,6 @@ You can pass the following keyword arguments to `BottleIntegration()`:
 ## Supported Versions
 
 - Bottle: 0.12.13+
-- Python: 2.7+
+- Python: 3.6+
+
+<Include name="python-use-older-sdk-for-legacy-support.mdx" />

docs/platforms/python/integrations/celery/index.mdx

@@ -161,5 +161,7 @@ my_task_b.apply_async(
 
 ## Supported Versions
 
-- Celery: 3.0+
-- Python: 2.7+ (Celery 3+), 3.6+ (Celery 5.0+), 3.7+ (Celery 5.1+)
+- Celery: 4.0+
+- Python: 3.6+
+
+<Include name="python-use-older-sdk-for-legacy-support.mdx" />

docs/platforms/python/integrations/default-integrations.mdx

@@ -84,53 +84,52 @@ _Import name: `sentry_sdk.integrations.threading.ThreadingIntegration`_
 
 Reports crashing threads.
 
-It also accepts an option `propagate_hub` that changes the way clients are transferred between threads, and transfers scope data (such as tags) from the parent thread to the child thread. This option is currently disabled (`False`) by default, but this will likely change in the future.
+This integration also accepts an option `propagate_scope`, which, when set to `True`, changes the way clients are transferred between threads and transfers scope data (such as tags) from the parent thread to the child thread. This option is currently disabled (`False`) by default, but this may change in the future.
 
-Next are two code samples that demonstrate what boilerplate you would have to write without `propagate_hub`. This boilerplate is still sometimes necessary if you want to propagate context data into a thread pool, for example.
+Next are two code samples that demonstrate what boilerplate you would have to write without `propagate_scope`. This boilerplate is still sometimes necessary if you want to propagate context data into a thread pool, for example.
 
 ### Manual propagation
 
 ```python
 import threading
-from sentry_sdk import Hub, init, set_tag, capture_message
 
-init(...)
+import sentry_sdk
 
-set_tag("mydata", 42)
+sentry_sdk.init(...)
 
-def run(thread_hub):
-    with thread_hub:
-        capture_message("hi")  # event will have `mydata` tag attached
+sentry_sdk.set_tag("mydata", 42)
+
+def run(thread_scope):
+    thread_scope.capture_message("hi")  # event will have `mydata` tag attached
 
 # We take all context data (the tags map and even the entire client
 # configuration), and pass it as explicit variable
 # into the thread.
-thread_hub = Hub(Hub.current)
-
-tr = threading.Thread(target=run, args=[thread_hub])
-tr.start()
-tr.join()
+with isolation_scope() as thread_scope:
+    tr = threading.Thread(target=run, args=[thread_scope])
+    tr.start()
+    tr.join()
 ```
 
 ### Example B: Automatic propagation
 
 ```python
 import threading
 
-from sentry_sdk import Hub, init, set_tag, capture_message
+import sentry_sdk
 from sentry_sdk.integrations.threading import ThreadingIntegration
 
-init(
+sentry_sdk.init(
     ...,
     integrations=[
-        ThreadingIntegration(propagate_hub=True),
+        ThreadingIntegration(propagate_scope=True),
     ],
 )
 
-set_tag("mydata", 42)
+sentry_sdk.set_tag("mydata", 42)
 
 def run():
-    capture_message("hi")  # event will have `mydata` tag attached
+    sentry_sdk.capture_message("hi")  # event will have `mydata` tag attached
 
 # The threading integration hooks into the stdlib to automatically pass
 # existing context data when a `Thread` is instantiated.

docs/platforms/python/integrations/django/index.mdx

@@ -145,8 +145,7 @@ You can pass the following keyword arguments to `DjangoIntegration()`:
 
 ## Supported Versions
 
-- Django 1.8-1.11 (Python: 2.7+)
-- Django 2.x (Python: 3.5+)
-- Django 3.x (Python: 3.6+)
-- Django 4.x (Python: 3.8+)
-- Django 5.x (Python: 3.10+)
+- Django 1.11+
+- Python 3.6+
+
+<Include name="python-use-older-sdk-for-legacy-support.mdx" />

docs/platforms/python/integrations/falcon/index.mdx

@@ -111,4 +111,6 @@ You can pass the following keyword arguments to `FalconIntegration()`:
 ## Supported Versions
 
 - Falcon: 1.4+
-- Python: 2.7+ (Falcon 1.4+), 3.5+ (Falcon 3.0+)
+- Python: 3.6+
+
+<Include name="python-use-older-sdk-for-legacy-support.mdx" />

docs/platforms/python/integrations/flask/index.mdx

@@ -104,5 +104,7 @@ You can pass the following keyword arguments to `FlaskIntegration()`:
 
 ## Supported Versions
 
-- Flask: 0.11+
-- Python: 2.7+ (Flask 0.11+), 3.6 (Flask 2.0+)
+- Flask: 1.0+
+- Python: 3.6+
+
+<Include name="python-use-older-sdk-for-legacy-support.mdx" />

docs/platforms/python/integrations/grpc/index.mdx

@@ -125,5 +125,7 @@ It takes a couple of moments for the data to appear in [sentry.io](https://sentr
 
 ## Supported Versions
 
-- grpcio: 1.21.1+
-- Python: 3.5+
+- grpcio: 1.39+
+- Python: 3.7+
+
+<Include name="python-use-older-sdk-for-legacy-support.mdx" />

docs/platforms/python/integrations/huey/index.mdx

@@ -56,5 +56,7 @@ take a couple of moments for the transaction to show up.
 
 ## Supported Versions
 
-- huey: 2.0.0+
-- Python: 2.7, 3.5+
+- huey: 2.0+
+- Python: 3.6+
+
+<Include name="python-use-older-sdk-for-legacy-support.mdx" />