From 59e13f67aa968f8648f0b49e4335bbb99128758d Mon Sep 17 00:00:00 2001 From: Jakob Keller <57402305+jakob-keller@users.noreply.github.com> Date: Sat, 24 Aug 2024 15:06:34 +0200 Subject: [PATCH 1/4] replace legacy repository URL --- docs/examples.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples.rst b/docs/examples.rst index 8ed11297..597bde52 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -2,7 +2,7 @@ Examples ============================= Below is a list of examples from `aiobotocore/examples -`_ +`_ Every example is a correct tiny python program. From 74366015b7698ce003c18e179acffc08988662a1 Mon Sep 17 00:00:00 2001 From: Jakob Keller <57402305+jakob-keller@users.noreply.github.com> Date: Sat, 24 Aug 2024 20:46:40 +0200 Subject: [PATCH 2/4] replace single backticks by double backticks in docs --- CONTRIBUTING.rst | 12 ++++++------ README.rst | 10 +++++----- docs/examples/dynamo_db/insertions.rst | 2 +- docs/examples/dynamo_db/tables.rst | 2 +- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 6e4466ee..0a1d7964 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -14,7 +14,7 @@ First of all, clone the repository:: $ git clone git@github.com:aio-libs/aiobotocore.git Create virtualenv with at least python3.8 (older versions are not supported). -For example, using *virtualenvwrapper* commands could look like:: +For example, using ``virtualenvwrapper`` commands could look like:: $ cd aiobotocore $ mkvirtualenv --python=`which python3.8` aiobotocore @@ -37,7 +37,7 @@ To run individual use following command:: Reporting an Issue ------------------ -If you have found issue with `aiobotocore` please do +If you have found issue with ``aiobotocore`` please do not hesitate to file an issue on the GitHub_ project. When filing your issue please make sure you can express the issue with a reproducible test case. @@ -47,8 +47,8 @@ that you can include. We never know what information will be pertinent when trying narrow down the issue. Please include at least the following information: -* Version of `aiobotocore` and `python`. -* Version fo `botocore`. +* Version of ``aiobotocore`` and ``python``. +* Version of ``botocore``. * Platform you're running on (OS X, Linux). @@ -56,7 +56,7 @@ Background and Implementation ----------------------------- aiobotocore adds async functionality to botocore by replacing certain critical methods in botocore classes with async versions. The best way to see how this -works is by working backwards from `AioEndpoint._request`. Because of this tight +works is by working backwards from ``AioEndpoint._request``. Because of this tight integration aiobotocore is typically version locked to a particular release of botocore. @@ -69,7 +69,7 @@ botocore calls eventually called. The best way I've seen to upgrade botocore support is by performing the following: 1. Download sources of the release of botocore you're trying to upgrade to, and the version of botocore that aiobotocore is currently locked to (see pyproject.toml) and do a folder based file comparison of the botocore folders (tools like DiffMerge are nice). -2. Manually apply the relevant changes to their aiobotocore equivalent(s). Note that sometimes new functions are added which will need to be overridden (like `__enter__` -> `__aenter__`) +2. Manually apply the relevant changes to their aiobotocore equivalent(s). Note that sometimes new functions are added which will need to be overridden (like ``__enter__`` -> ``__aenter__``) 3. Update the "project.optional-dependencies" in pyproject.toml to the versions which match the botocore version you are targeting. 4. Now do a directory diff between aiobotocore and your target version botocore directory to ensure the changes were propagated. diff --git a/README.rst b/README.rst index c721ce73..e24884b6 100644 --- a/README.rst +++ b/README.rst @@ -158,8 +158,8 @@ commonly used methods. | Kinesis | Basic methods tested | +----------------+-----------------------+ -Due to the way boto3 is implemented, its highly likely that even if services are not listed above that you can take any `boto3.client('service')` and -stick `await` infront of methods to make them async, e.g. `await client.list_named_queries()` would asynchronous list all of the named Athena queries. +Due to the way boto3 is implemented, its highly likely that even if services are not listed above that you can take any ``boto3.client('service')`` and +stick ``await`` in front of methods to make them async, e.g. ``await client.list_named_queries()`` would asynchronous list all of the named Athena queries. If a service is not listed here and you could do with some tests or examples feel free to raise an issue. @@ -199,7 +199,7 @@ Execute tests suite: Enable type checking and code completion ---------------------------------------- -Install types-aiobotocore_ that contains type annotations for `aiobotocore` +Install types-aiobotocore_ that contains type annotations for ``aiobotocore`` and all supported botocore_ services. .. code:: bash @@ -218,7 +218,7 @@ and all supported botocore_ services. Now you should be able to run Pylance_, pyright_, or mypy_ for type checking as well as code completion in your IDE. -For `types-aiobotocore-lite` package use explicit type annotations: +For ``types-aiobotocore-lite`` package use explicit type annotations: .. code:: python @@ -231,7 +231,7 @@ For `types-aiobotocore-lite` package use explicit type annotations: # type checking and code completion is now enabled for client -Full documentation for `types-aiobotocore` can be found here: https://youtype.github.io/types_aiobotocore_docs/ +Full documentation for ``types-aiobotocore`` can be found here: https://youtype.github.io/types_aiobotocore_docs/ Requirements diff --git a/docs/examples/dynamo_db/insertions.rst b/docs/examples/dynamo_db/insertions.rst index 44bf1ac8..7ef26dbd 100644 --- a/docs/examples/dynamo_db/insertions.rst +++ b/docs/examples/dynamo_db/insertions.rst @@ -9,7 +9,7 @@ if you stubborn, here is an example of inserting lots of items into Dynamo (it's What the code does is generates items (e.g. item0, item1, item2...) and writes them to a table "test" against a primary partition key called "pk" (with 5 read and 5 write units, no auto-scaling). -The `batch_write_item` method only takes a max of 25 items at a time, so the script computes 25 items, writes them, then does it all over again. +The ``batch_write_item`` method only takes a max of 25 items at a time, so the script computes 25 items, writes them, then does it all over again. After Dynamo has had enough, it will start throttling you and return any items that have not been written in the response. Once the script is being throttled, it will start sleeping for 5 seconds until the failed items have been successfully written, after that it will exit. diff --git a/docs/examples/dynamo_db/tables.rst b/docs/examples/dynamo_db/tables.rst index c9966615..0ff3030a 100644 --- a/docs/examples/dynamo_db/tables.rst +++ b/docs/examples/dynamo_db/tables.rst @@ -1,7 +1,7 @@ Table Creation ++++++++++++++ -When you create a DynamoDB table, it can take quite a while (especially if you add a few secondary index's). Instead of polling `describe_table` yourself, +When you create a DynamoDB table, it can take quite a while (especially if you add a few secondary index's). Instead of polling ``describe_table`` yourself, boto3 came up with "waiters" that will do all the polling for you. The following snippet shows how to wait for a DynamoDB table to be created in an async way. .. literalinclude:: ../../../examples/dynamodb_create_table.py From b604ffe311832312f11b285bb47c739cc8f64d72 Mon Sep 17 00:00:00 2001 From: Jakob Keller <57402305+jakob-keller@users.noreply.github.com> Date: Sat, 24 Aug 2024 20:48:30 +0200 Subject: [PATCH 3/4] leverage Sphinx file role in docs --- CONTRIBUTING.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0a1d7964..ff949d4d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -68,16 +68,16 @@ botocore calls eventually called. The best way I've seen to upgrade botocore support is by performing the following: -1. Download sources of the release of botocore you're trying to upgrade to, and the version of botocore that aiobotocore is currently locked to (see pyproject.toml) and do a folder based file comparison of the botocore folders (tools like DiffMerge are nice). +1. Download sources of the release of botocore you're trying to upgrade to, and the version of botocore that aiobotocore is currently locked to (see :file:`pyproject.toml`) and do a folder based file comparison of the botocore folders (tools like DiffMerge are nice). 2. Manually apply the relevant changes to their aiobotocore equivalent(s). Note that sometimes new functions are added which will need to be overridden (like ``__enter__`` -> ``__aenter__``) -3. Update the "project.optional-dependencies" in pyproject.toml to the versions which match the botocore version you are targeting. +3. Update the "project.optional-dependencies" in :file:`pyproject.toml` to the versions which match the botocore version you are targeting. 4. Now do a directory diff between aiobotocore and your target version botocore directory to ensure the changes were propagated. See next section describing types of changes we must validate and support. Hashes of Botocore Code (important) ----------------------------------- -Because of the way aiobotocore is implemented (see Background section), it is very tightly coupled with botocore. The validity of these couplings are enforced in test_patches.py. We also depend on some private properties in aiohttp, and because of this have entries in test_patches.py for this too. +Because of the way aiobotocore is implemented (see Background section), it is very tightly coupled with botocore. The validity of these couplings are enforced in :file:`test_patches.py`. We also depend on some private properties in aiohttp, and because of this have entries in :file:`test_patches.py` for this too. These patches are important to catch cases where botocore functionality was added/removed and needs to be reflected in our overridden methods. Changes include: @@ -85,14 +85,14 @@ These patches are important to catch cases where botocore functionality was adde * classes/methods being moved to new files * bodies of overridden methods updated -To ensure we catch and reflect this changes in aiobotocore, the test_patches.py file has the hashes of the parts of botocore we need to manually validate changes in. +To ensure we catch and reflect this changes in aiobotocore, the :file:`test_patches.py` file has the hashes of the parts of botocore we need to manually validate changes in. -test_patches.py file needs to be updated in two scenarios: +:file:`test_patches.py` file needs to be updated in two scenarios: -1. You're bumping the supported botocore/aiohttp version. In this case a failure in test_patches.py means you need to validate the section of code in aiohttp/botocore that no longer matches the hash in test_patches.py to see if any changes need to be reflected in aiobotocore which overloads, on depends on the code which triggered the hash mismatch. This could there are new parameters we weren't expecting, parameters that are no longer passed to said overriden function(s), or an overridden function which calls a modified botocore method. If this is a whole class collision the checks will be more extensive. +1. You're bumping the supported botocore/aiohttp version. In this case a failure in :file:`test_patches.py` means you need to validate the section of code in aiohttp/botocore that no longer matches the hash in test_patches.py to see if any changes need to be reflected in aiobotocore which overloads, on depends on the code which triggered the hash mismatch. This could there are new parameters we weren't expecting, parameters that are no longer passed to said overridden function(s), or an overridden function which calls a modified botocore method. If this is a whole class collision the checks will be more extensive. 2. You're implementing missing aiobotocore functionality, in which case you need to add entries for all the methods in botocore/aiohttp which you are overriding or depending on private functionality. For special cases, like when private attributes are used, you may have to hash the whole class so you can catch any case where the private property is used/updated to ensure it matches our expectations. -After you've validated the changes, you can update the hash in test_patches.py. +After you've validated the changes, you can update the hash in :file:`test_patches.py`. One would think we could just write enough unittests to catch all cases, however, this is impossible for two reasons: From 90ff11a8a516a5d4c923788765ec72016771a027 Mon Sep 17 00:00:00 2001 From: Jakob Keller <57402305+jakob-keller@users.noreply.github.com> Date: Sat, 24 Aug 2024 15:27:47 +0200 Subject: [PATCH 4/4] set `default_role = 'any'` in Sphinx configuration --- docs/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 2f51dbd3..0d2874a1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -184,3 +184,5 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} + +default_role = 'any'