release: 4.0.0

.github/workflows/ci.yml

@@ -78,7 +78,8 @@ jobs:
       - env:
           CLOUDFLARE_ACCOUNT_ID: f037e56e89293a057740de681ac9abbe
           CLOUDFLARE_EMAIL: [email protected]
-          CLOUDFLARE_ZONE_ID: 0da42c8d2132a9ddaf714f9e7c92011
+          CLOUDFLARE_ZONE_ID: 0da42c8d2132a9ddaf714f9e7c920711
           CLOUDFLARE_API_KEY: ${{ secrets.CLOUDFLARE_API_KEY }}
         run: |
-            rye run python ./examples/workers/ai/demo.py
+            rye run python ./examples/ai/demo.py
+            rye run python ./examples/dns/record.py

.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.1"
-}
+  ".": "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: 1493
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/cloudflare%2Fcloudflare-3d78f855257b55bbb80884f99c3802cae877968d140eed3557fcb2cdd5f937b3.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

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2024 Cloudflare
+   Copyright 2025 Cloudflare
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

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.
 ```
@@ -176,7 +172,7 @@ except cloudflare.APIStatusError as e:
     print(e.response)
 ```
 
-Error codes are as followed:
+Error codes are as follows:
 
 | Status Code | Error Type                 |
 | ----------- | -------------------------- |
@@ -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`:
@@ -319,8 +317,7 @@ If you need to access undocumented endpoints, params, or response properties, th
 #### Undocumented endpoints
 
 To make requests to undocumented endpoints, you can make requests using `client.get`, `client.post`, and other
-http verbs. Options on the client will be respected (such as retries) will be respected when making this
-request.
+http verbs. Options on the client will be respected (such as retries) when making this request.
 
 ```py
 import httpx
@@ -349,39 +346,67 @@ can also get all the extra fields on the Pydantic model as a dict with
 
 You can directly override the [httpx client](https://www.python-httpx.org/api/#client) to customize it for your use case, including:
 
-- Support for proxies
-- Custom transports
+- Support for [proxies](https://www.python-httpx.org/advanced/proxies/)
+- Custom [transports](https://www.python-httpx.org/advanced/transports/)
 - Additional [advanced](https://www.python-httpx.org/advanced/clients/) functionality
 
 ```python
+import httpx
 from cloudflare import Cloudflare, DefaultHttpxClient
 
 client = Cloudflare(
     # Or use the `CLOUDFLARE_BASE_URL` env var
     base_url="http://my.test.server.example.com:8083",
     http_client=DefaultHttpxClient(
-        proxies="http://my.test.proxy.example.com",
+        proxy="http://my.test.proxy.example.com",
         transport=httpx.HTTPTransport(local_address="0.0.0.0"),
     ),
 )
 ```
 
+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.
 
+```py
+from cloudflare import Cloudflare
+
+with Cloudflare() as client:
+  # make requests here
+  ...
+
+# HTTP client is now closed
+```
+
 ## Semantic versioning
 
 This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
 
 1. Changes that only affect static types, without breaking runtime behavior.
-1. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals)_.
+1. Changes to library internals which are technically public but not intended or documented for external use. 
 1. Changes that we do not expect to impact the vast majority of users in practice.
 
-> [!WARNING]
-> 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!