From b8b7ef1e8eebcc365ab7333191c2dc8481d336ae Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Wed, 18 Dec 2024 14:26:19 -0600 Subject: [PATCH] Add rstbebe to hooks + apply fixes Almost all of these are simple backtick substitutions and were part of our real user-facing documentation. One exception: because rstbebe detects code blocks by looking for a `.. code-block::`, it did not detect one case where `::` was used. Switching to a `.. code-block` also improves blacken-docs detection. rstbebe also does not detect RST comments (at least, current version), so there are "unnecessary" fixes in RST comments to make it pass. These are only in a couple of places. --- .pre-commit-config.yaml | 4 +++ changelog.rst | 28 +++++++++---------- docs/authorization/globus_app/apps.rst | 4 +-- docs/authorization/globus_app/config.rst | 2 +- .../token_caching/storage_adapters.rst | 2 +- .../examples/oauth2/globus_app.rst | 2 +- docs/services/index.rst | 8 +++--- docs/upgrading.rst | 6 ++-- tests/non-pytest/mypy-ignore-tests/README.rst | 2 +- 9 files changed, 31 insertions(+), 27 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d583c2c3d..c93c4a9f8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -41,6 +41,10 @@ repos: hooks: - id: isort name: "Sort python imports" +- repo: https://github.com/sirosen/rstbebe + rev: 0.2.0 + hooks: + - id: bad-backticks - repo: https://github.com/sirosen/slyp rev: 0.7.1 hooks: diff --git a/changelog.rst b/changelog.rst index bd393cfba..7585c9308 100644 --- a/changelog.rst +++ b/changelog.rst @@ -643,14 +643,14 @@ Added ``scope`` parameter as a string or iterable of strings. (:pr:`965`) - Moved scope parsing out of experimental. The ``Scope`` construct is now importable from - the top level `globus_sdk` module. (:pr:`966`) + the top level ``globus_sdk`` module. (:pr:`966`) - Support updating subscriptions assigned to flows in the Flows service. (:pr:`974`) Development ~~~~~~~~~~~ -- Fix concurrency problems in the test suite caused by isort's `.isorted` temporary files. (:pr:`973`) +- Fix concurrency problems in the test suite caused by isort's ``.isorted`` temporary files. (:pr:`973`) .. _changelog-3.39.0: @@ -726,8 +726,8 @@ v3.35.0 (2024-01-29) Added ~~~~~ -- Added a `session_required_mfa` parameter to the `AuthorizationParameterInfo` error - info object and `oauth2_get_authorize_url` method (:pr:`939`) +- Added a ``session_required_mfa`` parameter to the ``AuthorizationParameterInfo`` error + info object and ``oauth2_get_authorize_url`` method (:pr:`939`) Changed ~~~~~~~ @@ -745,7 +745,7 @@ Deprecated Fixed ~~~~~ -- Included documentation in `AuthorizationParameterInfo` for `session_required_policies` +- Included documentation in ``AuthorizationParameterInfo`` for ``session_required_policies`` (:pr:`939`) .. _changelog-3.34.0: @@ -1415,7 +1415,7 @@ Fixed with a usage error instead of being translated into the default set of ``requested_scopes`` -* Fix the type annotation for `max_sleep` on client transports to allow `float` +* Fix the type annotation for ``max_sleep`` on client transports to allow ``float`` values (:pr:`697`) .. _changelog-3.17.0: @@ -2063,10 +2063,10 @@ Added * Add ``iter_items`` as a method on ``TransferData`` and ``DeleteData`` (:pr:`488`) -* Add the `resource_server` property to client classes and objects. For example, - `TransferClient.resource_server` and `GroupsClient().resource_server` are now usable - to get the resource server string for the relevant services. `resource_server` is - documented as part of `globus_sdk.BaseClient` and may be `None`. (:pr:`489`) +* Add the ``resource_server`` property to client classes and objects. For example, + ``TransferClient.resource_server`` and ``GroupsClient().resource_server`` are now usable + to get the resource server string for the relevant services. ``resource_server`` is + documented as part of ``globus_sdk.BaseClient`` and may be ``None``. (:pr:`489`) * The implementation of several properties of ``GlobusHTTPResponse`` has changed (:pr:`497`) @@ -2106,10 +2106,10 @@ Added Changed ~~~~~~~ -* Adjust package metadata for `cryptography` dependency, specifying - `cryptography>=3.3.1` and no upper bound. This is meant to help mitigate - issues in which an older `cryptography` version is installed gets used in - spite of it being incompatible with `pyjwt[crypto]>=2.0` (:pr:`486`) +* Adjust package metadata for ``cryptography`` dependency, specifying + ``cryptography>=3.3.1`` and no upper bound. This is meant to help mitigate + issues in which an older ``cryptography`` version is installed gets used in + spite of it being incompatible with ``pyjwt[crypto]>=2.0`` (:pr:`486`) .. _changelog-3.0.3: diff --git a/docs/authorization/globus_app/apps.rst b/docs/authorization/globus_app/apps.rst index 14972f345..25b1e69b2 100644 --- a/docs/authorization/globus_app/apps.rst +++ b/docs/authorization/globus_app/apps.rst @@ -96,9 +96,9 @@ you can customize and how, see :ref:`globus_app_config`. :member-order: bysource .. - In the above class, "scope_requirements" is excluded because it's an `@property`. + In the above class, "scope_requirements" is excluded because it's a ``@property``. Sphinx wants to document it as a method but that's not how it's invoked. Instead - documentation is included in the class docstring as an `ivar`. + documentation is included in the class docstring as an ``ivar``. Implementations ^^^^^^^^^^^^^^^ diff --git a/docs/authorization/globus_app/config.rst b/docs/authorization/globus_app/config.rst index 2ad07582d..b2b27babd 100644 --- a/docs/authorization/globus_app/config.rst +++ b/docs/authorization/globus_app/config.rst @@ -19,7 +19,7 @@ Data Model .. In the above class, "token_validation_error_handler" is a callable so sphinx wants to document it as a method. Instead, we explicitly exclude it and document it in the - class docstring as an `ivar`. + class docstring as an ``ivar``. Providers ^^^^^^^^^ diff --git a/docs/authorization/token_caching/storage_adapters.rst b/docs/authorization/token_caching/storage_adapters.rst index b7148753e..112cbac1e 100644 --- a/docs/authorization/token_caching/storage_adapters.rst +++ b/docs/authorization/token_caching/storage_adapters.rst @@ -95,7 +95,7 @@ The :class:`SimpleJSONFileAdapter` is good for the "simplest possible" persistent storage, using a JSON file to store token data. :class:`MemoryAdapter` is even simpler still, and is great for writing and -testing code which uses the `StorageAdapter` interface backed by an in-memory +testing code which uses the ``StorageAdapter`` interface backed by an in-memory structure. The :class:`SQLiteAdapter` is more complex, for applications like the diff --git a/docs/experimental/examples/oauth2/globus_app.rst b/docs/experimental/examples/oauth2/globus_app.rst index 0719ca71c..424c14ce4 100644 --- a/docs/experimental/examples/oauth2/globus_app.rst +++ b/docs/experimental/examples/oauth2/globus_app.rst @@ -95,7 +95,7 @@ client's resource server and configuring the app as the service client's auth pr .. Note:: - ``ClientApp.__init__(...)`` requires the `client_secret` keyword argument. + ``ClientApp.__init__(...)`` requires the ``client_secret`` keyword argument. Native clients, which lack secrets, are not allowed. .. code-block:: python diff --git a/docs/services/index.rst b/docs/services/index.rst index 46b3a8903..3416a7e79 100644 --- a/docs/services/index.rst +++ b/docs/services/index.rst @@ -13,14 +13,14 @@ Once instantiated, a Client gives you high-level interface to make API calls, without needing to know Globus API endpoints or their various parameters. For example, you could use the :class:`TransferClient` to list your task history -very simply:: +very simply: + +.. code-block:: python from globus_sdk import TransferClient, AccessTokenAuthorizer # you must have a valid transfer token for this to work - tc = TransferClient( - authorizer=AccessTokenAuthorizer("TRANSFER_TOKEN_STRING") - ) + tc = TransferClient(authorizer=AccessTokenAuthorizer("TRANSFER_TOKEN_STRING")) print("My Last 25 Tasks:") # `filter` to get Delete Tasks (default is just Transfer Tasks) diff --git a/docs/upgrading.rst b/docs/upgrading.rst index cc3152644..dd0a541ee 100644 --- a/docs/upgrading.rst +++ b/docs/upgrading.rst @@ -256,9 +256,9 @@ it can be added to a request has changed as follows: Responses are always GlobusHTTPResponse ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In version 2, `GlobusHTTPResponse` inherited from a base class, -`GlobusResponse`. In version 3, the distinction has been eliminated and -responses are only `GlobusHTTPResponse`. +In version 2, ``GlobusHTTPResponse`` inherited from a base class, +``GlobusResponse``. In version 3, the distinction has been eliminated and +responses are only ``GlobusHTTPResponse``. This may appear in contexts where you type annotate or use ``isinstance`` checks to check the type of an object. diff --git a/tests/non-pytest/mypy-ignore-tests/README.rst b/tests/non-pytest/mypy-ignore-tests/README.rst index b4cd5014a..64ff17caa 100644 --- a/tests/non-pytest/mypy-ignore-tests/README.rst +++ b/tests/non-pytest/mypy-ignore-tests/README.rst @@ -8,4 +8,4 @@ This strategy is suggested as a lightweight test in the `Python Typing Quality Documentation `_. -These tests are run by `tox -e mypy` from the repo root. +These tests are run by ``tox -e mypy`` from the repo root.