release: 4.0.0

.github/workflows/release-doctor.yml

@@ -2,6 +2,8 @@ name: Release Doctor
 
 on:
   pull_request:
+    branches:
+      - main
   workflow_dispatch:
 
 concurrency:

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.1.0"
+  ".": "4.0.0"
 }

.stats.yml

@@ -1,2 +1,2 @@
-configured_endpoints: 1256
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/cloudflare%2Fcloudflare-923d8c7667b68c786e6c026c4f4851798943c7d68ea055c0043d9253413c5847.yml
+configured_endpoints: 1451
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/cloudflare%2Fcloudflare-a02ba2b0fe51558afee8cb212cbae6586f4ac2e7c20f46cbac6aeaf91a51f23e.yml

CONTRIBUTING.md

@@ -2,9 +2,13 @@
 
 ### With Rye
 
-We use [Rye](https://rye.astral.sh/) to manage dependencies so we highly recommend [installing it](https://rye.astral.sh/guide/installation/) as it will automatically provision a Python environment with the expected Python version.
+We use [Rye](https://rye.astral.sh/) to manage dependencies because it will automatically provision a Python environment with the expected Python version. To set it up, run:
 
-After installing Rye, you'll just have to run this command:
+```sh
+$ ./scripts/bootstrap
+```
+
+Or [install Rye manually](https://rye.astral.sh/guide/installation/) and run:
 
 ```sh
 $ rye sync --all-features
@@ -31,25 +35,25 @@ $ pip install -r requirements-dev.lock
 
 ## Modifying/Adding code
 
-Most of the SDK is generated code, and any modified code will be overridden on the next generation. The
-`src/cloudflare/lib/` and `examples/` directories are exceptions and will never be overridden.
+Most of the SDK is generated code. Modifications to code will be persisted between generations, but may
+result in merge conflicts between manual patches and changes from the generator. The generator will never
+modify the contents of the `src/cloudflare/lib/` and `examples/` directories.
 
 ## Adding and running examples
 
-All files in the `examples/` directory are not modified by the Stainless generator and can be freely edited or
-added to.
+All files in the `examples/` directory are not modified by the generator and can be freely edited or added to.
 
-```bash
+```py
 # add an example to examples/<your-example>.py
 
 #!/usr/bin/env -S rye run python
 …
 ```
 
-```
-chmod +x examples/<your-example>.py
+```sh
+$ chmod +x examples/<your-example>.py
 # run the example against your api
-./examples/<your-example>.py
+$ ./examples/<your-example>.py
 ```
 
 ## Using the repository from source
@@ -58,8 +62,8 @@ If you’d like to use the repository from source, you can either install from g
 
 To install via git:
 
-```bash
-pip install git+ssh://[email protected]/cloudflare/cloudflare-python.git
+```sh
+$ pip install git+ssh://[email protected]/cloudflare/cloudflare-python.git
 ```
 
 Alternatively, you can build from source and install the wheel file:
@@ -68,29 +72,29 @@ Building this package will create two files in the `dist/` directory, a `.tar.gz
 
 To create a distributable version of the library, all you have to do is run this command:
 
-```bash
-rye build
+```sh
+$ rye build
 # or
-python -m build
+$ python -m build
 ```
 
 Then to install:
 
 ```sh
-pip install ./path-to-wheel-file.whl
+$ pip install ./path-to-wheel-file.whl
 ```
 
 ## Running tests
 
 Most tests require you to [set up a mock server](https://github.com/stoplightio/prism) against the OpenAPI spec to run the tests.
 
-```bash
+```sh
 # you will need npm installed
-npx prism mock path/to/your/openapi.yml
+$ npx prism mock path/to/your/openapi.yml
 ```
 
-```bash
-rye run pytest
+```sh
+$ ./scripts/test
 ```
 
 ## Linting and formatting
@@ -100,14 +104,14 @@ This repository uses [ruff](https://github.com/astral-sh/ruff) and
 
 To lint:
 
-```bash
-rye run lint
+```sh
+$ ./scripts/lint
 ```
 
 To format and fix all ruff issues automatically:
 
-```bash
-rye run format
+```sh
+$ ./scripts/format
 ```
 
 ## Publishing and releases

README.md

@@ -2,7 +2,7 @@
 
 [![PyPI version](https://img.shields.io/pypi/v/cloudflare.svg)](https://pypi.org/project/cloudflare/)
 
-The Cloudflare Python library provides convenient access to the Cloudflare REST API from any Python 3.7+
+The Cloudflare Python library provides convenient access to the Cloudflare REST API from any Python 3.8+
 application. The library includes type definitions for all request params and response fields,
 and offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).
 
@@ -26,10 +26,8 @@ import os
 from cloudflare import Cloudflare
 
 client = Cloudflare(
-    # This is the default and can be omitted
-    api_email=os.environ.get("CLOUDFLARE_EMAIL"),
-    # This is the default and can be omitted
-    api_key=os.environ.get("CLOUDFLARE_API_KEY"),
+    api_email=os.environ.get("CLOUDFLARE_EMAIL"),  # This is the default and can be omitted
+    api_key=os.environ.get("CLOUDFLARE_API_KEY"),  # This is the default and can be omitted
 )
 
 zone = client.zones.create(
@@ -55,10 +53,8 @@ import asyncio
 from cloudflare import AsyncCloudflare
 
 client = AsyncCloudflare(
-    # This is the default and can be omitted
-    api_email=os.environ.get("CLOUDFLARE_EMAIL"),
-    # This is the default and can be omitted
-    api_key=os.environ.get("CLOUDFLARE_API_KEY"),
+    api_email=os.environ.get("CLOUDFLARE_EMAIL"),  # This is the default and can be omitted
+    api_key=os.environ.get("CLOUDFLARE_API_KEY"),  # This is the default and can be omitted
 )
 
 
@@ -92,7 +88,7 @@ List methods in the Cloudflare API are paginated.
 This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
 
 ```python
-import cloudflare
+from cloudflare import Cloudflare
 
 client = Cloudflare()
 
@@ -108,7 +104,7 @@ Or, asynchronously:
 
 ```python
 import asyncio
-import cloudflare
+from cloudflare import AsyncCloudflare
 
 client = AsyncCloudflare()
 
@@ -141,7 +137,7 @@ Or just work directly with the returned data:
 ```python
 first_page = await client.accounts.list()
 for account in first_page.result:
-    print(account)
+    print(account.id)
 
 # Remove `await` for non-async usage.
 ```
@@ -247,12 +243,14 @@ Note that requests that time out are [retried twice by default](#retries).
 
 We use the standard library [`logging`](https://docs.python.org/3/library/logging.html) module.
 
-You can enable logging by setting the environment variable `CLOUDFLARE_LOG` to `debug`.
+You can enable logging by setting the environment variable `CLOUDFLARE_LOG` to `info`.
 
 ```shell
-$ export CLOUDFLARE_LOG=debug
+$ export CLOUDFLARE_LOG=info
 ```
 
+Or to `debug` for more verbose logging.
+
 ### How to tell whether `None` means `null` or missing
 
 In an API response, a field may be explicitly `null`, or missing entirely; in either case, its value is `None` in this library. You can differentiate the two cases with `.model_fields_set`:
@@ -366,6 +364,12 @@ client = Cloudflare(
 )
 ```
 
+You can also customize the client on a per-request basis by using `with_options()`:
+
+```python
+client.with_options(http_client=DefaultHttpxClient(...))
+```
+
 ### Managing HTTP resources
 
 By default the library closes underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__). You can manually close the client using the `.close()` method if desired, or with a context manager that closes when exiting.
@@ -382,6 +386,21 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 > In addition to the above, changes to type names, structure or methods _may_ occur as we stabilise the automated codegen pipeline. This will be removed in the future once we are further along and the service owner OpenAPI schemas have reached a higher maturity level where changes are not as constant.
 > If this isn't suitable for your project, we recommend pinning to a known version or using the previous major version.
 
+### Determining the installed version
+
+If you've upgraded to the latest version but aren't seeing any new features you were expecting then your python environment is likely still using an older version.
+
+You can determine the version that is being used at runtime with:
+
+```py
+import cloudflare
+print(cloudflare.__version__)
+```
+
 ## Requirements
 
-Python 3.7 or higher.
+Python 3.8 or higher.
+
+## Contributing
+
+See [the contributing documentation](./CONTRIBUTING.md).

SECURITY.md

@@ -1,3 +1,3 @@
 # Reporting Security Vulnerabilities
 
-Please see [this page](https://www.cloudflare.com/.well-known/security.txt) for information on how to report a vulnerability to Cloudflare. Thanks!
+Please see [this page](https://www.cloudflare.com/.well-known/security.txt) for information on how to report a vulnerability to Cloudflare. Thanks!