Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 FrameBridge release automation
|
3a539fb4e4 | ||
|
FrameBridge release automation
|
cdd980e1eb | ||
|
FrameBridge
|
b8c9b713d8 |
No files matched your search
+2
-2
@@ -2,9 +2,9 @@
|
|||||||
|
|
||||||
The owner-approved first-party license is GNU GPL version 3 only (GPL-3.0-only), selected October 25, 2026. Apache-2.0 was an earlier first-party proposal and remains applicable to third-party components that use it. The complete GPL is in [LICENSE](LICENSE), with scope in [LICENSING.md](LICENSING.md).
|
The owner-approved first-party license is GNU GPL version 3 only (GPL-3.0-only), selected October 25, 2026. Apache-2.0 was an earlier first-party proposal and remains applicable to third-party components that use it. The complete GPL is in [LICENSE](LICENSE), with scope in [LICENSING.md](LICENSING.md).
|
||||||
|
|
||||||
The current release target is FrameBridge 0.3.1, installer FrameBridge-0.3.1.deb. Historical RC7 and Community Preview artifacts retain their separate identities.
|
FrameBridge 0.3.4 has separate Debian 13, Ubuntu 24.04 and Linux Mint 22.x amd64 release profiles. Signature and publication status belong to its accompanying release record. The [official download page](https://framebridge.betancourt.one/download/) and each artifact's release record identify its source and signatures. Historical 0.3.3, 0.3.1, RC7 and Community Preview artifacts retain their separate identities; their versioned filenames do not identify the current installer.
|
||||||
|
|
||||||
The pinned Python/Rust dependency notices and source delivery were reconciled in the retained native terms review. The 0.3.1 preparation additionally identifies the OpenAI tunnel-client as third-party Apache-2.0 material, retains its notices, and supplies exact h1-verified source archives and notices for its 47 embedded Go modules. Its own development-build source commit is not embedded and remains a provenance limit.
|
The pinned Python/Rust dependency notices and source delivery were reconciled in the retained native terms review. The retained OpenAI tunnel-client is third-party Apache-2.0 material. Its notices and exact h1-verified source archives and notices for its 47 embedded Go modules remain included. Its own development-build source commit is not embedded and remains a provenance limit. The dependency-source assets retain their historical 0.3.1 filenames; this does not change the FrameBridge release version or assert an independent rebuild of those components.
|
||||||
|
|
||||||
Public delivery is complete only when the actual matching installer, FrameBridge source, dependency-source assets, supplements and notices are downloadable with verified hashes. Private collection does not establish public availability. The final release delivery record is authoritative for staged or public status; this file does not assert that the port is open or public downloads are live.
|
Public delivery is complete only when the actual matching installer, FrameBridge source, dependency-source assets, supplements and notices are downloadable with verified hashes. Private collection does not establish public availability. The final release delivery record is authoritative for staged or public status; this file does not assert that the port is open or public downloads are live.
|
||||||
|
|
||||||
|
|||||||
+2
-2
@@ -6,7 +6,7 @@ The owner selected GNU General Public License version 3 only, SPDX identifier GP
|
|||||||
|
|
||||||
The grant covers original FrameBridge code and project documentation that the rightsholders are entitled to license. Recipients may use, study, modify and redistribute that material under the GPL. Modified private copies and lawful independent distributions do not require submitting a pull request to this project. Original blog article text explicitly marked for that purpose uses CC-BY-SA-4.0 under [blog/LICENSING.md](blog/LICENSING.md); media and separately licensed components retain their own terms.
|
The grant covers original FrameBridge code and project documentation that the rightsholders are entitled to license. Recipients may use, study, modify and redistribute that material under the GPL. Modified private copies and lawful independent distributions do not require submitting a pull request to this project. Original blog article text explicitly marked for that purpose uses CC-BY-SA-4.0 under [blog/LICENSING.md](blog/LICENSING.md); media and separately licensed components retain their own terms.
|
||||||
|
|
||||||
[licensing/SOURCE-LICENSE-SCOPE.json](licensing/SOURCE-LICENSE-SCOPE.json) records classification and provenance. File location is not proof of ownership. Preserve [COPYRIGHT.md](COPYRIGHT.md) and applicable notices.
|
[licensing/SOURCE-LICENSE-SCOPE.json](licensing/SOURCE-LICENSE-SCOPE.json) records historical classification and provenance; the matching release SOURCE-ARCHIVE-MANIFEST.json identifies the complete current source set. File location is not proof of ownership. Preserve [COPYRIGHT.md](COPYRIGHT.md) and applicable notices.
|
||||||
|
|
||||||
## Third-party material
|
## Third-party material
|
||||||
|
|
||||||
@@ -18,7 +18,7 @@ The tunnel executable identifies its own module as a development build without a
|
|||||||
|
|
||||||
## Source delivery
|
## Source delivery
|
||||||
|
|
||||||
Distribute the matching FrameBridge 0.3.1 source archive beside its installer, the immutable shared Python/Rust dependency-source asset, the new tunnel-client dependency-source supplement and retained notices. [Source availability](licensing/third-party/SOURCE-AVAILABILITY.md) identifies the files and hashes.
|
Distribute the matching FrameBridge 0.3.4 source archive beside each of its three distribution-profile installers, the immutable shared Python/Rust dependency-source asset, the new tunnel-client dependency-source supplement and retained notices. [Source availability](licensing/third-party/SOURCE-AVAILABILITY.md) identifies the files and hashes.
|
||||||
|
|
||||||
The unchanged Certifi source arrangement retains its exact upstream source assets, original notice, full MPL-2.0 text and recipient access instructions. The historical Mozilla certdata revision remains unidentified. No independent native-wheel or tunnel-client rebuild is claimed. These are provenance and reproducibility limits, not claims that unavailable proof has been obtained.
|
The unchanged Certifi source arrangement retains its exact upstream source assets, original notice, full MPL-2.0 text and recipient access instructions. The historical Mozilla certdata revision remains unidentified. No independent native-wheel or tunnel-client rebuild is claimed. These are provenance and reproducibility limits, not claims that unavailable proof has been obtained.
|
||||||
|
|
||||||
|
|||||||
+30
-30
@@ -1,37 +1,37 @@
|
|||||||
# FrameBridge 0.3.1 source archive
|
# FrameBridge 0.3.4 corresponding source
|
||||||
|
|
||||||
This archive preserves the repository layout needed by the offline builder.
|
This archive supplies the project source and the reviewed cp313 and cp312 vendor
|
||||||
From this directory, run python3 source/packaging/build_expanded.py to build
|
inputs for Debian 13, Ubuntu 24.04 and Linux Mint 22.x on amd64. Keep its matching
|
||||||
FrameBridge-0.3.1.deb. The builder writes source/build and source/release;
|
SOURCE-ARCHIVE-MANIFEST.json sidecar beside the archive. Signatures, publication
|
||||||
it does not install or start FrameBridge. Debian's dpkg-deb and the documented
|
and actual OS lifecycle acceptance are recorded separately; assembly alone does
|
||||||
build prerequisites must already be available.
|
not certify them. Historical signed assets retain their immutable identities.
|
||||||
|
|
||||||
Original FrameBridge material is GNU GPL version 3 only. Read LICENSE,
|
The offline builder needs Python 3, dpkg/dpkg-deb and the documented host build
|
||||||
LICENSING.md, COPYRIGHT.md, LICENSE-STATUS.md and OFFICIAL-RELEASES.md for
|
prerequisites. It never fetches dependencies, installs packages or starts services.
|
||||||
scope, attribution, third-party terms and the official-release trust model.
|
Extract the archive beside its matching sidecar and run from the extracted root:
|
||||||
|
|
||||||
The project source asset is accompanied by these separate dependency assets:
|
python3 source/packaging/build_expanded.py --target debian13-amd64-py313 --public-release --source-manifest ../SOURCE-ARCHIVE-MANIFEST.json
|
||||||
|
python3 source/packaging/build_expanded.py --target ubuntu24.04-amd64-py312 --vendor-dir source/target-vendors/cp312 --public-release --source-manifest ../SOURCE-ARCHIVE-MANIFEST.json
|
||||||
|
python3 source/packaging/build_expanded.py --target mint22-amd64-py312 --vendor-dir source/target-vendors/cp312 --public-release --source-manifest ../SOURCE-ARCHIVE-MANIFEST.json
|
||||||
|
|
||||||
|
Public-release mode verifies the archive hash, every current project source file
|
||||||
|
and the selected reviewed vendor identity before assembling a package. It does
|
||||||
|
not assert an independent rebuild of third-party native wheels or tunnel-client.
|
||||||
|
--check-vendor validates inputs without staging a package.
|
||||||
|
|
||||||
|
Original FrameBridge material is GNU GPL version 3 only. Third-party material
|
||||||
|
retains its applicable terms. Read LICENSE, LICENSING.md, COPYRIGHT.md and the
|
||||||
|
source-delivery records. Distribute these separate, unchanged dependency assets
|
||||||
|
with the release; their historical names do not identify the installer version:
|
||||||
|
|
||||||
- FrameBridge-0.3.1-Community-Preview1-dependency-sources.tar.gz
|
- FrameBridge-0.3.1-Community-Preview1-dependency-sources.tar.gz
|
||||||
82,606,998 bytes
|
Bytes: 82606998
|
||||||
SHA-256 64540a85bd65eac3f394d8c0a967cacbc00e112676d57d644dcd1bb691c1926a
|
SHA-256: 64540a85bd65eac3f394d8c0a967cacbc00e112676d57d644dcd1bb691c1926a
|
||||||
- FrameBridge-0.3.1-tunnel-client-dependency-sources.tar.gz
|
- FrameBridge-0.3.1-tunnel-client-dependency-sources.tar.gz
|
||||||
26,941,745 bytes
|
Bytes: 26941745
|
||||||
SHA-256 6445d4f0e773aba833fe5c610fbae54102b92de2ce636438f769f21e890c2bd9
|
SHA-256: 6445d4f0e773aba833fe5c610fbae54102b92de2ce636438f769f21e890c2bd9
|
||||||
|
|
||||||
The Preview1 filename deliberately preserves the identity of an immutable
|
The exact own-source revision of the retained tunnel executable is not asserted.
|
||||||
shared asset. Retain licensing/third-party/R2-SUPPLEMENTS.json and its referenced
|
Retain the R2 source-notice supplements, both dependency indices and original
|
||||||
source notices with the dependency sources. The source indices and
|
notices. Private profiles, credentials, QA logs, build outputs, Git history and
|
||||||
SOURCE-AVAILABILITY.md there record scope and provenance. Do not substitute
|
unpublished blog drafts are excluded from the archive allowlist.
|
||||||
unrelated archives. The retained tunnel executable is not claimed to have been
|
|
||||||
independently rebuilt from an identified own-source revision.
|
|
||||||
|
|
||||||
The blog directory contains licensing policies and the post template.
|
|
||||||
Editorial article drafts are omitted because they are not source build inputs.
|
|
||||||
|
|
||||||
Only source/evidence/BASELINE.json is included from technical evidence. Runtime
|
|
||||||
profiles, private QA logs, generated build/release files and Git history are
|
|
||||||
outside the source archive allowlist.
|
|
||||||
|
|
||||||
A completed archive or builder run is not a declaration of public readiness.
|
|
||||||
Release checksums, signatures and publication status are recorded separately.
|
|
||||||
@@ -1,10 +1,12 @@
|
|||||||
# FrameBridge
|
# FrameBridge
|
||||||
|
|
||||||
**Bring your ChatGPT conversations to Linux computers you control.**
|
**Administer your Linux network from a connected conversation.**
|
||||||
|
|
||||||
Run a task on your own machine, return to the same Bash terminal, inspect an X11 desktop, or select an enrolled computer. ChatGPT remains hosted; FrameBridge runs the tools on your Linux computers.
|
Use a central gateway and enrolled nodes to administer Linux computers you control. Run commands and return to persistent Bash terminals; an existing X11 desktop adds optional graphical tools. ChatGPT remains hosted; FrameBridge runs the tools on your Linux computers.
|
||||||
|
|
||||||
> **Unsigned release candidate: `0.3.2`.** This source preparation promotes the compatibility candidate; it is not a signed public release. Final artifact validation and signing are recorded separately. The signed 0.3.1 release remains a different artifact. Read the [compatibility scope and history](docs/LINUX-COMPATIBILITY-CANDIDATE.md); use the exact artifact release record when choosing a package.
|
> **FrameBridge 0.3.4.** Release builds cover Debian 13, Ubuntu 24.04 and Linux Mint 22.x on amd64. Choose the exact distribution profile on the [official download page](https://framebridge.betancourt.one/download/). Verify the matching release record, package signatures and signed APT metadata before installation.
|
||||||
|
|
||||||
|
This release adds `fb health` / `fb --json health`, confirmed destination identity in Fleet results, native persistent startup improvements and reduced disk writes while idle. The source archive, release packages and external acceptance record identify the exact released code. See the [0.3.4 release notes](docs/RELEASE-NOTES-0.3.4.md).
|
||||||
|
|
||||||
## Start here
|
## Start here
|
||||||
|
|
||||||
@@ -18,22 +20,22 @@ Start on the Linux computer you want to connect, with a person at its terminal o
|
|||||||
|
|
||||||
### 1. Install the matching package
|
### 1. Install the matching package
|
||||||
|
|
||||||
The compatibility candidate has separate native Python builds; it is not one interchangeable `.deb` for every Linux system.
|
The release has three native Python builds. Choose the package matching the distribution and system Python.
|
||||||
|
|
||||||
| Distribution | Architecture | System Python | Candidate package profile |
|
| Distribution | Architecture | System Python | Release package profile |
|
||||||
| --- | --- | --- | --- |
|
| --- | --- | --- | --- |
|
||||||
| Debian 13 | amd64 / x86_64 | 3.13 | `debian13-amd64-py313` |
|
| Debian 13 | amd64 / x86_64 | 3.13 | `debian13-amd64-py313` |
|
||||||
| Ubuntu 24.04 | amd64 / x86_64 | 3.12 | `ubuntu24.04-amd64-py312` |
|
| Ubuntu 24.04 | amd64 / x86_64 | 3.12 | `ubuntu24.04-amd64-py312` |
|
||||||
| Linux Mint 22.x | amd64 / x86_64 | 3.12 | `mint22-amd64-py312` |
|
| Linux Mint 22.x | amd64 / x86_64 | 3.12 | `mint22-amd64-py312` |
|
||||||
|
|
||||||
The preceding compatibility candidate `0.3.2~compat.20261027.3` passed installation, normal and optional virtual-runtime startup, actual MCP HTTP/SSE exchanges, terminal and cleanup tests on Debian 13, Ubuntu 24.04 and Mint 22.3 VMs. Mint also passed its Cinnamon window-capture test with its existing WebSocket library unchanged. This 0.3.2 source preparation preserves that runtime behavior; the exact final package bytes require their own artifact validation and release signatures. Ubuntu 26.04 and LMDE 7 builds remain experimental; other distributions, older releases and CPU architectures are outside this candidate's scope.
|
Version-specific signed APT update and managed-service lifecycle results belong to the accompanying release acceptance record. Ubuntu 26.04, LMDE 7, other distributions, older releases and other CPU architectures are outside the validated scope of this release. Earlier compatibility experiments are recorded in the [compatibility history](docs/LINUX-COMPATIBILITY-CANDIDATE.md).
|
||||||
|
|
||||||
Verify official releases with the independently trusted project key as described in [Official releases](OFFICIAL-RELEASES.md). A candidate's recorded SHA-256 identifies its reviewed file; it is not a release signature. Candidate packages are for reviewed pilots.
|
Verify the signing-key fingerprint, package checksum and detached signature using the instructions on the [official download page](https://framebridge.betancourt.one/download/). Historical release records remain in [Official releases](OFFICIAL-RELEASES.md). A checksum identifies a file; the release signature authenticates it with the independently trusted project key.
|
||||||
|
|
||||||
For example, with the **Mint** candidate downloaded into the current directory:
|
For example, with the **Mint** 0.3.4 package downloaded into the current directory:
|
||||||
|
|
||||||
~~~bash
|
~~~bash
|
||||||
sudo apt install ./FrameBridge-0.3.2-mint22-amd64-py312.deb
|
sudo apt install ./FrameBridge-0.3.4-mint22-amd64-py312.deb
|
||||||
~~~
|
~~~
|
||||||
|
|
||||||
Use the corresponding profile filename on Debian or Ubuntu. Review APT's proposed changes for the actual computer. Installation places the software on disk; it does not establish a ChatGPT connection or replace the system Python.
|
Use the corresponding profile filename on Debian or Ubuntu. Review APT's proposed changes for the actual computer. Installation places the software on disk; it does not establish a ChatGPT connection or replace the system Python.
|
||||||
@@ -81,6 +83,8 @@ fb help commands --json
|
|||||||
|
|
||||||
JSON output is versioned and never prompts. `INTERACTION_REQUIRED` gives an action for the owner's normal terminal. The agent workflow helps an existing shell-based assistant install and diagnose FrameBridge; it does not claim every AI client is a tested replacement for ChatGPT.
|
JSON output is versioned and never prompts. `INTERACTION_REQUIRED` gives an action for the owner's normal terminal. The agent workflow helps an existing shell-based assistant install and diagnose FrameBridge; it does not claim every AI client is a tested replacement for ChatGPT.
|
||||||
|
|
||||||
|
For remote work, identify the receiver and execution target separately. `LOCAL` means the current FrameBridge receiver, not a fixed ASUS destination or the computer displaying the conversation. Read the enrolled-node inventory and use a confirmed alias or ID when selecting another computer. Legacy connectors can have different defaults; verify routing before replacing one with another.
|
||||||
|
|
||||||
`fb` and `framebridge` are names for the same program. Read `fb help` for the English guide and `fb help compatibility` for legacy commands.
|
`fb` and `framebridge` are names for the same program. Read `fb help` for the English guide and `fb help compatibility` for legacy commands.
|
||||||
|
|
||||||
## Pause, stop or remove
|
## Pause, stop or remove
|
||||||
@@ -104,11 +108,13 @@ Versioned source archives include the FrameBridge implementation, builders, test
|
|||||||
|
|
||||||
Use `python3 source/packaging/build_expanded.py --help` for package build profiles and `python3 source/packaging/archive_sources.py --help` for source archiving. Building does not install, start, sign or publish the product.
|
Use `python3 source/packaging/build_expanded.py --help` for package build profiles and `python3 source/packaging/archive_sources.py --help` for source archiving. Building does not install, start, sign or publish the product.
|
||||||
|
|
||||||
Read [CONTRIBUTING.md](CONTRIBUTING.md) to propose a change and [SECURITY.md](SECURITY.md) for security reports. Useful compatibility reports name the exact distribution, version, Python version, package profile and tests actually performed. Independent copies retain their applicable software freedoms; they must not be presented as maintainer-approved releases.
|
Read [CONTRIBUTING.md](CONTRIBUTING.md) to propose a change and [SECURITY.md](SECURITY.md) for security reports. Use [project issues](https://framebridge.betancourt.one/git/gerardo/framebridge/issues) for non-sensitive bug reports and installation questions. Useful compatibility reports name the exact distribution, version, Python version, package profile and tests actually performed. Independent copies retain their applicable software freedoms; they must not be presented as maintainer-approved releases.
|
||||||
|
|
||||||
Project home and 0.3.2 publication origin: https://betancourt.one/framebridge/
|
The [claims and evidence boundaries](docs/CLAIMS-AND-LIMITS.md) distinguish package installation, connection and operation results. The [operations roadmap](docs/OPERATIONS-ROADMAP.md) describes proposed follow-up work and acceptance checks; it is not a list of features already delivered.
|
||||||
|
|
||||||
Use the corresponding-source archive identified in each release record. When that record marks the source mirror published, its read-only HTTP Git endpoint is `https://betancourt.one/framebridge/git/framebridge.git`. Final 0.3.2 publication is pending; this source preparation does not claim that the new packages or mirror are already live.
|
Project home: https://framebridge.betancourt.one/
|
||||||
|
|
||||||
|
The public Git repository is `https://framebridge.betancourt.one/git/gerardo/framebridge.git`. For the exact 0.3.4 release, use the signed `v0.3.4` tag or its signed corresponding-source archive from the download page. The repositories, package downloads and source archive are published; normal owner authentication and connection setup are still required on a newly installed computer.
|
||||||
|
|
||||||
Programming: **ChatGPT**.
|
Programming: **ChatGPT**.
|
||||||
Original concept and project coordination: **Gerardo Betancourt**.
|
Original concept and project coordination: **Gerardo Betancourt**.
|
||||||
|
|||||||
@@ -1,24 +0,0 @@
|
|||||||
# FrameBridge 0.3.3
|
|
||||||
|
|
||||||
FrameBridge administers Linux computers on a home network through a shared command-line interface for the human administrator and authorized agents. The language model remains hosted.
|
|
||||||
|
|
||||||
## Changes
|
|
||||||
|
|
||||||
- The desktop console reconnects to the existing official console window when the same tmux session contains other windows. It preserves the working shell and unrelated windows, and displays jobs from the selected profile. Recognized legacy desktop entries and console wrappers can be migrated to the packaged command with private backups.
|
|
||||||
- Forward package upgrades record active managed profiles before replacing files. A detached upgrade worker waits for DPKG to finish, then restarts only those profiles in independent user services. It preserves existing connection processes, profile settings, enrollment and boot policy, and records readiness separately from package installation. Stopped profiles remain stopped.
|
|
||||||
- The release provides separate amd64 builds and signed APT suites for Debian 13 (`trixie`), Ubuntu 24.04 (`noble`) and Linux Mint 22.x (`mint22`). Use the package for the distribution actually installed; keep its system Python.
|
|
||||||
- The public documentation uses the canonical website and Gitea repository under `framebridge.betancourt.one` and describes network administration as the primary workflow. Desktop tools remain auxiliary.
|
|
||||||
|
|
||||||
## Updating
|
|
||||||
|
|
||||||
After configuring the matching signed APT source, use the normal package manager to install or update `framebridge-original-expanded`. Inspect `fb status` after an upgrade. A successful APT command confirms package installation; the upgrade worker records runtime restart and readiness independently. An upgrade from a stopped profile does not connect it automatically.
|
|
||||||
|
|
||||||
## Compatibility
|
|
||||||
|
|
||||||
Physical desktop input requires a compatible active X11 session. Native Wayland control is not certified. The guarded x86-64 X11 text backend supports active keyboard group 0 and its documented modifier restrictions.
|
|
||||||
|
|
||||||
Legacy integrations can have a different default execution target from the current receiver. Preserve explicit target routing or use a compatibility adapter when migrating existing clients. Replacing an endpoint without checking its default target is not a compatibility guarantee.
|
|
||||||
|
|
||||||
## Validation
|
|
||||||
|
|
||||||
The release is being validated against the three distribution profiles. Build, signature, APT and live upgrade results are recorded in the accompanying release verification manifest; publication and installation must be verified against the actual signed artifacts.
|
|
||||||
@@ -1,5 +1,9 @@
|
|||||||
# FrameBridge release notes
|
# FrameBridge release notes
|
||||||
|
|
||||||
|
## 0.3.4
|
||||||
|
|
||||||
|
Native persistent startup improvements, lower idle disk writes, local health reporting and confirmed Fleet destinations. The release has three amd64 distribution profiles and matching source with both Python ABIs. See [the complete 0.3.4 notes](docs/RELEASE-NOTES-0.3.4.md); signatures and actual lifecycle results are recorded with the release artifacts.
|
||||||
|
|
||||||
## Unreleased — private production pilot fixes
|
## Unreleased — private production pilot fixes
|
||||||
|
|
||||||
Private pilot validation remains in progress; these changes are not a public release.
|
Private pilot validation remains in progress; these changes are not a public release.
|
||||||
|
|||||||
@@ -0,0 +1,451 @@
|
|||||||
|
{
|
||||||
|
"omitted_vendor_abis": [
|
||||||
|
"cp314"
|
||||||
|
],
|
||||||
|
"release_profiles": [
|
||||||
|
"debian13-amd64-py313",
|
||||||
|
"ubuntu24.04-amd64-py312",
|
||||||
|
"mint22-amd64-py312"
|
||||||
|
],
|
||||||
|
"schema": 1,
|
||||||
|
"validation_status": "release_source",
|
||||||
|
"vendors": {
|
||||||
|
"cp312": {
|
||||||
|
"native_extensions": [
|
||||||
|
"_cffi_backend.cpython-312-x86_64-linux-gnu.so",
|
||||||
|
"cryptography/hazmat/bindings/_rust.abi3.so",
|
||||||
|
"pydantic_core/_pydantic_core.cpython-312-x86_64-linux-gnu.so",
|
||||||
|
"rpds/rpds.cpython-312-x86_64-linux-gnu.so"
|
||||||
|
],
|
||||||
|
"packages": [
|
||||||
|
{
|
||||||
|
"name": "annotated-types",
|
||||||
|
"version": "0.8.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "anyio",
|
||||||
|
"version": "4.15.1",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "attrs",
|
||||||
|
"version": "26.1.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "certifi",
|
||||||
|
"version": "2026.7.22",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "cffi",
|
||||||
|
"version": "2.1.1",
|
||||||
|
"wheel_tags": [
|
||||||
|
"cp312-cp312-manylinux_2_17_x86_64",
|
||||||
|
"cp312-cp312-manylinux2014_x86_64"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "click",
|
||||||
|
"version": "8.5.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "cryptography",
|
||||||
|
"version": "50.0.1",
|
||||||
|
"wheel_tags": [
|
||||||
|
"cp311-abi3-manylinux_2_34_x86_64"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "h11",
|
||||||
|
"version": "0.16.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "httpcore",
|
||||||
|
"version": "1.0.9",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "httpx",
|
||||||
|
"version": "0.28.1",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "httpx-sse",
|
||||||
|
"version": "0.4.3",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "idna",
|
||||||
|
"version": "3.20",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "jsonschema",
|
||||||
|
"version": "4.26.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "jsonschema-specifications",
|
||||||
|
"version": "2025.9.1",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "mcp",
|
||||||
|
"version": "1.26.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "pycparser",
|
||||||
|
"version": "3.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "pydantic",
|
||||||
|
"version": "2.13.5",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "pydantic-core",
|
||||||
|
"version": "2.46.5",
|
||||||
|
"wheel_tags": [
|
||||||
|
"cp312-cp312-manylinux_2_17_x86_64",
|
||||||
|
"cp312-cp312-manylinux2014_x86_64"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "pydantic-settings",
|
||||||
|
"version": "2.15.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "pyjwt",
|
||||||
|
"version": "2.14.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "python-dotenv",
|
||||||
|
"version": "1.2.3",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "python-multipart",
|
||||||
|
"version": "0.0.32",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "referencing",
|
||||||
|
"version": "0.37.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "rpds-py",
|
||||||
|
"version": "2026.6.3",
|
||||||
|
"wheel_tags": [
|
||||||
|
"cp312-cp312-manylinux_2_17_x86_64",
|
||||||
|
"cp312-cp312-manylinux2014_x86_64"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "sse-starlette",
|
||||||
|
"version": "3.4.11",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "starlette",
|
||||||
|
"version": "1.7.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "typing-extensions",
|
||||||
|
"version": "4.16.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "typing-inspection",
|
||||||
|
"version": "0.4.4",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "uvicorn",
|
||||||
|
"version": "0.53.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"path": "source/target-vendors/cp312",
|
||||||
|
"vendor_sha256": "f4ea1dfb4f71b11eb1a9963bfe55dc6f94e6b10e927f77a7bd9b62433a29ddf1"
|
||||||
|
},
|
||||||
|
"cp313": {
|
||||||
|
"native_extensions": [
|
||||||
|
"_cffi_backend.cpython-313-x86_64-linux-gnu.so",
|
||||||
|
"cryptography/hazmat/bindings/_rust.abi3.so",
|
||||||
|
"pydantic_core/_pydantic_core.cpython-313-x86_64-linux-gnu.so",
|
||||||
|
"rpds/rpds.cpython-313-x86_64-linux-gnu.so"
|
||||||
|
],
|
||||||
|
"packages": [
|
||||||
|
{
|
||||||
|
"name": "annotated-types",
|
||||||
|
"version": "0.8.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "anyio",
|
||||||
|
"version": "4.15.1",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "attrs",
|
||||||
|
"version": "26.1.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "certifi",
|
||||||
|
"version": "2026.7.22",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "cffi",
|
||||||
|
"version": "2.1.1",
|
||||||
|
"wheel_tags": [
|
||||||
|
"cp313-cp313-manylinux_2_17_x86_64",
|
||||||
|
"cp313-cp313-manylinux2014_x86_64"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "click",
|
||||||
|
"version": "8.5.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "cryptography",
|
||||||
|
"version": "50.0.1",
|
||||||
|
"wheel_tags": [
|
||||||
|
"cp311-abi3-manylinux_2_34_x86_64"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "h11",
|
||||||
|
"version": "0.16.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "httpcore",
|
||||||
|
"version": "1.0.9",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "httpx",
|
||||||
|
"version": "0.28.1",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "httpx-sse",
|
||||||
|
"version": "0.4.3",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "idna",
|
||||||
|
"version": "3.20",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "jsonschema",
|
||||||
|
"version": "4.26.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "jsonschema-specifications",
|
||||||
|
"version": "2025.9.1",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "mcp",
|
||||||
|
"version": "1.26.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "pycparser",
|
||||||
|
"version": "3.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "pydantic",
|
||||||
|
"version": "2.13.5",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "pydantic-core",
|
||||||
|
"version": "2.46.5",
|
||||||
|
"wheel_tags": [
|
||||||
|
"cp313-cp313-manylinux_2_17_x86_64",
|
||||||
|
"cp313-cp313-manylinux2014_x86_64"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "pydantic-settings",
|
||||||
|
"version": "2.15.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "pyjwt",
|
||||||
|
"version": "2.14.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "python-dotenv",
|
||||||
|
"version": "1.2.3",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "python-multipart",
|
||||||
|
"version": "0.0.32",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "referencing",
|
||||||
|
"version": "0.37.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "rpds-py",
|
||||||
|
"version": "2026.6.3",
|
||||||
|
"wheel_tags": [
|
||||||
|
"cp313-cp313-manylinux_2_17_x86_64",
|
||||||
|
"cp313-cp313-manylinux2014_x86_64"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "sse-starlette",
|
||||||
|
"version": "3.4.11",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "starlette",
|
||||||
|
"version": "1.7.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "typing-extensions",
|
||||||
|
"version": "4.16.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "typing-inspection",
|
||||||
|
"version": "0.4.4",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "uvicorn",
|
||||||
|
"version": "0.53.0",
|
||||||
|
"wheel_tags": [
|
||||||
|
"py3-none-any"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"path": "source/sources/original-geranas/FrameBridge-Fleet-Hub/vendor",
|
||||||
|
"vendor_sha256": "80e2917f19003e95f74a6250ee08043cb90681100faf510c0e034843740c0950"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"version": "0.3.4"
|
||||||
|
}
|
||||||
+26
-13
@@ -1,23 +1,36 @@
|
|||||||
# Claims and evidence boundaries
|
# Claims and evidence boundaries
|
||||||
|
|
||||||
The current version is `0.3.1~community.20261026.2`, a separate candidate from RC7 and Preview 1.
|
The latest signed release is **FrameBridge 0.3.4**, with separate amd64 packages for Debian 13, Ubuntu 24.04 and Linux Mint 22.x. The [official download page](https://framebridge.betancourt.one/download/) identifies the actual artifacts, signatures and corresponding source. A later default-branch documentation change does not rewrite the signed tag or an installed package.
|
||||||
|
|
||||||
|
## Current release scope
|
||||||
|
|
||||||
| Statement | Evidence and boundary |
|
| Statement | Evidence and boundary |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| Preview 2 unit suite | 376 tests passed in 22.351 seconds; focused peer regression also passed. |
|
| Distribution profiles | Debian 13 / CPython 3.13, Ubuntu 24.04 / CPython 3.12 and Mint 22.x / CPython 3.12, all amd64. Ubuntu 26.04, LMDE 7, other architectures and other distributions are outside this release's validated scope. |
|
||||||
| Preview 2 package and VM | Pending at documentation freeze; no new VM acceptance or artifact hash is invented here. |
|
| Signed APT updates | Actual update and managed-service lifecycle checks passed on Debian 13, Ubuntu 24.04 and Mint 22.3 VMs. This is not acceptance of every physical installation or every future package. |
|
||||||
| Preview 1 | Historical record: 368 tests and a reproducible package build. |
|
| Release identity | The signed tag and release record identify released source and bytes. A source checkout, successful build or checksum alone does not establish an official signed release. |
|
||||||
| RC7 | Historical record: 361 tests, reproducible package, Debian 13 VM lifecycle and real ChatGPT/console acceptance. |
|
| Source tests | Run `python3 tools/run_tests.py` from a source checkout. A test result applies to the source revision and environment actually tested; historical test counts are not current results. |
|
||||||
| ChatGPT connection | Manual owner account consent; the model remains hosted while tools run on selected owner-controlled computers. |
|
| Installed documentation | Read the guide matching the installed version. A newer repository README cannot update an older installed manual. Report contradictory release labels with the package version and file path. |
|
||||||
| Persistent console | Session continuity is not a promise that every process survives reboot. |
|
|
||||||
| Independent FBEXEC tasks | Repeated maintainer experience with non-overlapping work; no certified isolation or simultaneous execution of every command. |
|
## Operation results
|
||||||
| Graphical control | One controller per shared desktop is a recommendation, not an automatic lock. |
|
|
||||||
|
| Statement | Evidence and boundary |
|
||||||
|
| --- | --- |
|
||||||
|
| ChatGPT connection | Manual owner account consent; the model remains hosted while tools run on selected owner-controlled computers. Installing the package or assigning an account label does not prove connection. |
|
||||||
|
| Receiver and target | `LOCAL` denotes the current receiver. Another computer must be selected using a confirmed enrolled alias or ID. A legacy endpoint's default destination is not a routing guarantee for a replacement endpoint. |
|
||||||
|
| Query and task success | A successful status query or outer tool wrapper does not prove readiness or successful inner execution. Read the target, exit code and operation result, then verify the intended effect. |
|
||||||
|
| Persistent console | Bash continuity lasts while the session survives; it does not promise survival across reboot. Preserve the existing console and unrelated work unless changing them is authorized. |
|
||||||
|
| Independent FBEXEC tasks | Repeated maintainer experience with non-overlapping work; no certified isolation or guarantee that every command can run concurrently. |
|
||||||
|
| Graphical control | Requires a compatible active X11 session and observed capture/input success. Native Wayland control is not certified. One controller per shared desktop is an operating recommendation, not an automatic lock. |
|
||||||
|
| Real images and demonstrations | Use complete authentic captures. Identify virtual displays and terminal text separately. Conceptual animation is illustration, not evidence of execution. |
|
||||||
| sudo | Actual privileges depend on the Unix account and normal authentication; an authorization flag does not grant root. |
|
| sudo | Actual privileges depend on the Unix account and normal authentication; an authorization flag does not grant root. |
|
||||||
| Real images and demo | Use complete authentic captures. A fresh Preview 2 real recording is pending; conceptual animation is illustration. |
|
| Recovery | Pause, stop, boot policy, revocation and removal have different effects. A package downgrade can revoke administrative helper grants; retaining a previous package is not proof of automatic rollback. |
|
||||||
| Dependency terms/source | Scoped technical terms review and exact source availability recorded with delivery conditions; component terms remain in force. |
|
| Dependency terms/source | Scoped technical terms review and exact source availability are recorded with delivery conditions; component terms and provenance limits remain in force. |
|
||||||
|
|
||||||
|
Earlier RC7 and Community Preview results remain historical records. They must not be substituted for the build, signature, installation or acceptance evidence of a later artifact. The [operations roadmap](OPERATIONS-ROADMAP.md) distinguishes proposed work from delivered capabilities.
|
||||||
|
|
||||||
## Retained control components
|
## Retained control components
|
||||||
|
|
||||||
The retained development broker defaults to its existing 127.0.0.1 peer only. Repeatable --control-peer IP_LITERAL arguments add explicit peers. Invalid entries fail before Store creation/binding; checks use the real client address, not proxy headers. Retained RPC UID, host, client/socket and administrator identity guards remain unchanged. Normal Expanded handling uses the generic terminal entrypoint; FRAMEBRIDGE_ENABLE_GERAMEG_CUA_TTY=0 is not an effective guard.
|
The retained development broker defaults to its existing 127.0.0.1 peer only. Repeatable `--control-peer IP_LITERAL` arguments add explicit peers. Invalid entries fail before Store creation/binding; checks use the real client address, not proxy headers. Retained RPC UID, host, client/socket and administrator identity guards remain unchanged. Normal Expanded handling uses the generic terminal entrypoint; `FRAMEBRIDGE_ENABLE_GERAMEG_CUA_TTY=0` is not an effective guard.
|
||||||
|
|
||||||
The classic lab-target map is empty, while the compatibility route remains available for explicit integrator configuration. Do not describe retained code as entirely inactive. Further executable edits require identifiable source and candidate-specific validation.
|
The classic lab-target map is empty, while the compatibility route remains available for explicit integrator configuration. Do not describe retained code as entirely inactive. Executable changes require an identifiable source revision and validation of the changed behavior.
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
# FrameBridge — command guide
|
# FrameBridge — command guide
|
||||||
|
|
||||||
Version: 0.3.3 | Guide schema: 1
|
Version: 0.3.4 | Guide schema: 1
|
||||||
|
|
||||||
This reference is generated from the shared CLI/MCP guide. Use the matching installed version.
|
This reference is generated from the shared CLI/MCP guide. Use the matching installed version.
|
||||||
|
|
||||||
@@ -36,7 +36,6 @@ fb --json status
|
|||||||
Install the package built for your exact Debian 13, Ubuntu 24.04 or Linux Mint 22.x amd64 profile. These are the three release profiles; other distributions and architectures are outside this release. Keep the distribution system Python: 3.13 on Debian 13, 3.12 on Ubuntu 24.04 and Mint 22.x. Use the matching signed APT suite: trixie, noble or mint22. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.
|
Install the package built for your exact Debian 13, Ubuntu 24.04 or Linux Mint 22.x amd64 profile. These are the three release profiles; other distributions and architectures are outside this release. Keep the distribution system Python: 3.13 on Debian 13, 3.12 on Ubuntu 24.04 and Mint 22.x. Use the matching signed APT suite: trixie, noble or mint22. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.
|
||||||
|
|
||||||
~~~sh
|
~~~sh
|
||||||
sudo apt install ./framebridge-expanded_0.3.3_amd64.deb
|
|
||||||
fb connect
|
fb connect
|
||||||
~~~
|
~~~
|
||||||
|
|
||||||
@@ -80,6 +79,7 @@ fb status runtime
|
|||||||
fb status boot
|
fb status boot
|
||||||
fb status console
|
fb status console
|
||||||
fb doctor
|
fb doctor
|
||||||
|
fb health
|
||||||
fb setup
|
fb setup
|
||||||
fb console
|
fb console
|
||||||
fb help
|
fb help
|
||||||
@@ -231,7 +231,7 @@ fb nodes status
|
|||||||
|
|
||||||
### Targets
|
### Targets
|
||||||
|
|
||||||
LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty --node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.
|
LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Fleet results include requested_target, resolved_target, node_id, hostname and transport from the confirmed descriptor. The compatibility target field can remain LOCAL; resolved_target names the actual local computer. Unknown targets never fall back to LOCAL. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty --node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.
|
||||||
|
|
||||||
### Transport trust
|
### Transport trust
|
||||||
|
|
||||||
@@ -344,12 +344,21 @@ fb status boot
|
|||||||
|
|
||||||
### Doctor
|
### Doctor
|
||||||
|
|
||||||
doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes. Candidate eligibility checks the exact OS release, amd64 architecture, package profile and CPython ABI before starting native components. Debian 13/LMDE 7 use cp313, Ubuntu 24.04/Mint 22.x use cp312, and Ubuntu 26.04 uses cp314. A matching profile does not establish a tested installation; never repair an ABI mismatch by replacing system Python or weakening package dependencies.
|
doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes. Eligibility checks the exact OS release, amd64 architecture, package profile and CPython ABI before starting native components. The published 0.3.3 scope is Debian 13 with cp313 and Ubuntu 24.04/Mint 22.x with cp312. LMDE 7 and Ubuntu 26.04 builder experiments remain outside that validated scope. A matching profile or a successful development build does not establish a tested installation; never repair an ABI mismatch by replacing system Python or weakening package dependencies.
|
||||||
|
|
||||||
~~~sh
|
~~~sh
|
||||||
fb doctor
|
fb doctor
|
||||||
~~~
|
~~~
|
||||||
|
|
||||||
|
### Local health summary
|
||||||
|
|
||||||
|
health combines this local profile's existing status and prerequisite observations into an allowlisted report. It identifies LOCAL as this computer and reports the profile, role, connection intent, local tools, boot policy and desktop availability. It never starts, repairs, connects, changes boot policy or creates an absent profile. It does not scan the fleet or probe terminal commands, screen capture or input. States are healthy, paused, degraded, unavailable and unconfigured. An intentional connection pause can be healthy; missing information cannot. JSON result.ok describes observation completeness; result.health.healthy describes health. Health exits 0 for a complete healthy or intentionally paused observation and 1 for degraded, unavailable or unconfigured state. The CLI version is not proof of the running version. Detailed troubleshooting remains local in status and doctor.
|
||||||
|
|
||||||
|
~~~sh
|
||||||
|
fb health
|
||||||
|
fb --json health
|
||||||
|
~~~
|
||||||
|
|
||||||
### Logs and progress
|
### Logs and progress
|
||||||
|
|
||||||
Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.
|
Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.
|
||||||
|
|||||||
@@ -4,12 +4,14 @@ This is a setup and verification workflow for an assistant that **already has au
|
|||||||
|
|
||||||
The currently tested connection is the manual ChatGPT workflow. A coding assistant can help prepare it through the CLI; this document does not claim drop-in integration with every AI client.
|
The currently tested connection is the manual ChatGPT workflow. A coding assistant can help prepare it through the CLI; this document does not claim drop-in integration with every AI client.
|
||||||
|
|
||||||
Source preparation: **0.3.2, unsigned release candidate**, promoted from compatibility revision `0.3.2~compat.20261027.3` after its Debian 13, Ubuntu 24.04 and Mint 22.3 VM checks passed. Check the exact artifact release record before installation; this prior behavior evidence does not verify the final package bytes or claim public availability.
|
Latest signed release: **0.3.3**, published for Debian 13, Ubuntu 24.04 and Linux Mint 22.x on amd64. Use the exact profile, signatures and source record from the [official download page](https://framebridge.betancourt.one/download/). A later source checkout can contain unreleased changes; it is not evidence that a new package has been built, signed or published. Historical compatibility-candidate checks remain separate from validation of the actual release artifacts.
|
||||||
|
|
||||||
## Before handing over
|
## Before handing over
|
||||||
|
|
||||||
Give the assistant the computer you want to work on, the intended task, and the local path of the reviewed matching package. Use the [README's package matrix](../README.md#1-install-the-matching-package). If this is a pilot beside an existing installation, identify a new isolated `--state-dir` and the existing services that must remain running.
|
Give the assistant the computer you want to work on, the intended task, and the local path of the reviewed matching package. Use the [README's package matrix](../README.md#1-install-the-matching-package). If this is a pilot beside an existing installation, identify a new isolated `--state-dir` and the existing services that must remain running.
|
||||||
|
|
||||||
|
Name both the computer receiving the assistant's tool call and the intended execution target. `LOCAL` means the current FrameBridge receiver, not a fixed computer called ASUS or the computer displaying the chat. Discover enrolled nodes and use their confirmed aliases or IDs. A legacy connector can have a different default target; changing endpoints does not preserve that default automatically.
|
||||||
|
|
||||||
Do not put passwords, tunnel IDs, server access keys or browser codes in the prompt. The owner will enter them in the local hidden prompts. An MCP server access key is not an OpenAI API key.
|
Do not put passwords, tunnel IDs, server access keys or browser codes in the prompt. The owner will enter them in the local hidden prompts. An MCP server access key is not an OpenAI API key.
|
||||||
|
|
||||||
## Copy this into your assistant
|
## Copy this into your assistant
|
||||||
@@ -20,12 +22,16 @@ Help me install and verify FrameBridge on this Linux computer.
|
|||||||
Target computer: [the computer to which you already have authorized shell access]
|
Target computer: [the computer to which you already have authorized shell access]
|
||||||
Reviewed package: [absolute local path to the matching FrameBridge .deb]
|
Reviewed package: [absolute local path to the matching FrameBridge .deb]
|
||||||
Scope: [new installation, or the specifically authorized pilot/profile]
|
Scope: [new installation, or the specifically authorized pilot/profile]
|
||||||
|
Receiver and execution target: [identify both; do not assume LOCAL means ASUS]
|
||||||
|
|
||||||
First establish where you are running. Inspect the distribution/version,
|
First establish where you are running. Inspect the distribution/version,
|
||||||
architecture and system Python. Match them to the package's release profile.
|
architecture and system Python. Match them to the package's release profile.
|
||||||
Read the project's README and the installed versioned help where available.
|
Read the project's README and the installed versioned help where available.
|
||||||
Reuse FrameBridge's existing CLI and package; do not invent a replacement
|
Reuse FrameBridge's existing CLI and package; do not invent a replacement
|
||||||
transport or rewrite the application to complete setup.
|
transport or rewrite the application to complete setup.
|
||||||
|
Confirm the receiver and selected target before the first remote operation.
|
||||||
|
Use an enrolled alias or ID for another computer and inspect the effective
|
||||||
|
target in the response. Do not fall back to a different computer on error.
|
||||||
|
|
||||||
Use my existing task authorization. Complete the authorized preparatory work
|
Use my existing task authorization. Complete the authorized preparatory work
|
||||||
before asking for information or a decision that is actually missing.
|
before asking for information or a decision that is actually missing.
|
||||||
@@ -70,6 +76,8 @@ If desktop access is in scope, first identify the actual X11 session and use
|
|||||||
a new test window. A virtual display must be described as virtual. Terminal
|
a new test window. A virtual display must be described as virtual. Terminal
|
||||||
text is not a screen capture, and a VM's desktop is not the owner's physical
|
text is not a screen capture, and a VM's desktop is not the owner's physical
|
||||||
display. Do not claim a screenshot or successful input unless it was observed.
|
display. Do not claim a screenshot or successful input unless it was observed.
|
||||||
|
Coordinate one controller at a time for a shared desktop. Preserve existing
|
||||||
|
console windows and their work unless changing them is part of the task.
|
||||||
|
|
||||||
Check actual command exit codes and operation results. An outer tool wrapper's
|
Check actual command exit codes and operation results. An outer tool wrapper's
|
||||||
success flag is not proof that its inner command succeeded. Distinguish local
|
success flag is not proof that its inner command succeeded. Distinguish local
|
||||||
|
|||||||
@@ -0,0 +1,29 @@
|
|||||||
|
# Small Linux fleet operations: development scope
|
||||||
|
|
||||||
|
This document records proposed follow-up work after the signed 0.3.3 release. It is not a feature-availability statement, a release announcement or a promise of unattended administration. The initial scope remains owner-controlled Debian 13, Ubuntu 24.04 and Mint 22.x amd64 computers administered by one responsible person.
|
||||||
|
|
||||||
|
The `0.3.4` release source implements an initial **local-only** `health` summary and additive confirmed destination identity in Fleet results. It also consolidates the installed documentation, permits secure administrator-owned ancestors of the user's service directory and reduces durable idle status writes. These changes do not complete the wider acceptance items below. See [release notes](RELEASE-NOTES-0.3.4.md).
|
||||||
|
|
||||||
|
## Acceptance order
|
||||||
|
|
||||||
|
| Priority | Intended improvement | Acceptance evidence required |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 1 | Coherent installation and diagnosis | The package, CLI, MCP guide and website agree on version and supported profiles. An administrator outside the project completes installation, connection and a first harmless query using the documentation; record time and assistance needed. |
|
||||||
|
| 2 | Unambiguous execution destination | Show receiver and effective target separately. An explicit target never falls back to another machine. Cover unknown and duplicate names and differences from legacy defaults. |
|
||||||
|
| 3 | Unified read-only health | Reuse existing status, doctor and inventory tools. Report observation time, source and unavailable/error states. Distinguish disk capacity from free space, package presence from readiness and screenshot availability from input control. |
|
||||||
|
| 4 | Five versioned procedures | Begin with general diagnosis, a failed service, DNS diagnosis, APT diagnosis and a FrameBridge update. Record prerequisites, exact procedure version, proposed change, applicable authorization, post-check and a recovery route where supported. Read-only checks must not repair implicitly. |
|
||||||
|
| 5 | Jobs and technical history | A later conversation can identify the target, operation, result and remaining work without reconstructing the entire chat. Test disconnect/reconnect behavior and duplicate submissions. Export useful records without secrets. |
|
||||||
|
| 6 | Small external pilot | Use a separate installation per customer initially. Record installation effort, incidents, completed tasks, support time and willingness to renew before extending the platform. |
|
||||||
|
|
||||||
|
## Preserve the current operating model
|
||||||
|
|
||||||
|
- Keep `fb` / `framebridge` as the shared interface for the administrator and authorized agents.
|
||||||
|
- Retain the indicative console and existing work. A health view complements it.
|
||||||
|
- Use terminal and command tools for routine administration, with graphical CUA available for tasks that need a real desktop. Describe actual session and display limits.
|
||||||
|
- Keep normal OS/browser authentication in the owner's normal interface. Reuse task authorization; do not add repetitive approvals to harmless observations.
|
||||||
|
- Retain explicit connection intent and boot policy. An update must not start a profile that was intentionally stopped.
|
||||||
|
- Treat transport as a component. Another MCP client or platform is supported only after a documented interoperability test.
|
||||||
|
|
||||||
|
## Deferred expansion
|
||||||
|
|
||||||
|
Shared multi-customer hosting, broad Windows/macOS/DSM support, native Wayland control, a new tunnel/VPN and an autonomous always-on technician are separate projects. They need their own requirements and acceptance evidence. The initial commercial experiment is a scoped installation and maintenance service, not a claim that FrameBridge already supplies a full enterprise RMM platform.
|
||||||
@@ -0,0 +1,34 @@
|
|||||||
|
# Historical FrameBridge 0.3.4 development notes
|
||||||
|
|
||||||
|
This record describes the earlier private I/O candidate. The final 0.3.4 source and current scope are documented in [the release notes](RELEASE-NOTES-0.3.4.md).
|
||||||
|
|
||||||
|
Version: `0.3.4~dev.20261029.3`.
|
||||||
|
|
||||||
|
This is a development candidate following the signed 0.3.3 release. It does not replace the signed tag, public downloads or stable APT channels. Build success is not installation, reboot, independent-user or multi-customer acceptance.
|
||||||
|
|
||||||
|
This I/O candidate is based on `0.3.4~dev.20261029.1`. The separate `.2` node-initialization experiment is not included.
|
||||||
|
|
||||||
|
## Changes
|
||||||
|
|
||||||
|
- `fb health` and `fb --json health` combine existing local status and prerequisite observations. The report names the receiving computer and profile, separates query success from health and connection intent, and leaves unknown values unknown. It does not create an absent profile, start a service, repair configuration or probe terminal/desktop control.
|
||||||
|
- Health exits 0 for a complete healthy or intentionally paused observation and 1 for degraded, unavailable or unconfigured state. JSON `result.ok` describes observation completeness; `result.health.healthy` describes health. A requested pause is not healthy when the observed tunnel still runs.
|
||||||
|
- Fleet read, EXEC, screen and CUA results include `requested_target`, `resolved_target`, `node_id`, `hostname` and `transport` from the confirmed route. Existing `target` semantics remain compatible. Upstream result fields cannot replace the confirmed identity. Errors after resolution retain that identity; unresolved targets never acquire an invented local identity.
|
||||||
|
- Installed documentation is assembled from the reviewed current source, including the corrected signed 0.3.3 publication record, support scope, first-connection instructions and canonical homepage. Shared CLI/MCP/manpage references are regenerated for this development version.
|
||||||
|
- Managed connection setup accepts administrator-owned `.config` and `.config/systemd` ancestors when they are directories without group/other write permission. The final `systemd/user` directory must still belong to the connecting user. Symbolic links, other-account ownership and unsafe permissions are rejected. Setup does not change existing directory ownership or permissions.
|
||||||
|
- Managed-worker state is persisted on transitions instead of repeatedly syncing the same state while idle. Connection liveness heartbeats use the account's validated `/run/user/<uid>` runtime directory when available; profiles without it retain a bounded durable fallback. Status still requires a fresh heartbeat bound to the same worker identity. Existing permissions and credentials are unchanged. These changes do not claim that all application or system disk activity stops.
|
||||||
|
|
||||||
|
## Native startup and the GERANAS deployment gap
|
||||||
|
|
||||||
|
Normal `fb connect` already installs the managed user service, protects the connection credential, enables startup without an interactive login and records connection intent. Installation of a package without connection setup cannot establish a new authenticated tunnel. APT preserves a manual profile's existing policy rather than silently enabling it.
|
||||||
|
|
||||||
|
The affected GERANAS deployment had been left as a manually started central profile without the native managed connection setup. External recovery services did not complete that setup and did not share the CLI's lifecycle controls. This candidate fixes the service-account directory compatibility issue needed for native setup; it does not add another external startup mechanism or fabricate managed installation records.
|
||||||
|
|
||||||
|
Source tests and package builds do not prove reconnection after a reboot. Acceptance must separately record a real changed boot ID, native service startup, connection availability and execution through the intended route. No reboot acceptance is claimed by these release notes.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
The three build profiles remain Debian 13 amd64/cp313, Ubuntu 24.04 amd64/cp312 and Linux Mint 22.x amd64/cp312. The new health command observes one selected **local profile**, not the fleet. Invoke it on the intended host and pass `--state-dir` when using a nondefault profile. Runtime readiness and capability availability are not fresh proofs that a command, screenshot or input operation succeeded.
|
||||||
|
|
||||||
|
The existing indicative console, connection intent, boot policy, user profiles, privileged-helper lifecycle and authentication workflow are preserved. Normal browser and operating-system authentication stay in the owner's normal interface. No new enrollment, transport, GUI or recurring approval mechanism is introduced.
|
||||||
|
|
||||||
|
The next product acceptance items are documented in [the operations roadmap](OPERATIONS-ROADMAP.md). Versioned repair workflows, a multi-host health dashboard, customer isolation and other MCP clients remain proposed work until separately implemented and tested.
|
||||||
@@ -0,0 +1,29 @@
|
|||||||
|
# FrameBridge 0.3.4
|
||||||
|
|
||||||
|
Release profiles: Debian 13 amd64/Python 3.13, Ubuntu 24.04 amd64/Python 3.12 and Linux Mint 22.x amd64/Python 3.12.
|
||||||
|
|
||||||
|
## Network administration and observation
|
||||||
|
|
||||||
|
- `fb health` and `fb --json health` summarize the selected local profile without starting, repairing or connecting it. Query completeness, health, connection intent and unknown observations remain distinct.
|
||||||
|
- Fleet command, terminal, screen and CUA results identify the confirmed receiving computer, node and transport. Result fields cannot replace the destination identity established by routing.
|
||||||
|
- Transient broker failures recover with bounded backoff and fresh signed nonces. Acknowledgement retries retain the computed result and do not reexecute commands. Authentication, TLS and malformed-response failures remain terminal.
|
||||||
|
|
||||||
|
## Persistent startup and idle writes
|
||||||
|
|
||||||
|
- Native managed startup accepts secure administrator-owned service-directory ancestors without changing their ownership or permissions. The final user-service directory remains private to its account.
|
||||||
|
- Node startup avoids redundant privileged setup when the required account settings already exist. Existing credential grants still follow the privileged cleanup lifecycle.
|
||||||
|
- The managed supervisor persists worker-state transitions instead of repeatedly syncing identical state. Connection heartbeats use the validated account runtime directory when available, with the same process identity and 15-second freshness checks. A bounded durable fallback remains for environments without a user runtime directory.
|
||||||
|
- APT upgrades preserve profiles and existing startup policy. Normal connection setup provisions the native managed service; installing a package alone cannot establish an authenticated ChatGPT connection.
|
||||||
|
|
||||||
|
## Console, compatibility and delivery
|
||||||
|
|
||||||
|
- The indicative console and persistent terminal remain available. Real-screen capture, terminal transcripts and explicitly selected virtual displays are identified separately.
|
||||||
|
- The same English command guide serves the CLI, MCP help, installed manual and tutorial. Other distributions, Wayland and CPU architectures are outside this release's validated scope.
|
||||||
|
- One corresponding-source archive includes the reviewed cp313 and cp312 vendor inputs for all three packages. Public-release assembly requires its matching manifest and checks the archive, current source and selected vendor hashes.
|
||||||
|
- Original material remains GPL-3.0-only. Preserve both immutable dependency-source assets, third-party notices and stated provenance limits. No new independent native-wheel or tunnel-client rebuild is claimed.
|
||||||
|
|
||||||
|
## Validation and release identity
|
||||||
|
|
||||||
|
Artifact hashes, signatures, signed APT metadata and actual distribution lifecycle results belong to the accompanying release record. Build assembly does not assert that those external checks passed or that a download has been published. Retain the source archive and its sidecar manifest together when rebuilding official release profiles.
|
||||||
|
|
||||||
|
Programming: ChatGPT. Original concept and project coordination: Gerardo Betancourt.
|
||||||
@@ -1,4 +1,4 @@
|
|||||||
# Third-party terms and source delivery — FrameBridge 0.3.1
|
# Third-party terms and source delivery — FrameBridge 0.3.4
|
||||||
|
|
||||||
This scoped release record combines the retained Python/Rust review with the 0.3.1 OpenAI tunnel-client notice supplement. It does not relabel incorporated components as FrameBridge-owned GPL material.
|
This scoped release record combines the retained Python/Rust review with the 0.3.1 OpenAI tunnel-client notice supplement. It does not relabel incorporated components as FrameBridge-owned GPL material.
|
||||||
|
|
||||||
@@ -20,7 +20,7 @@ The executable's own module is marked (devel) and has no embedded VCS revision.
|
|||||||
|
|
||||||
## Delivery conditions and limits
|
## Delivery conditions and limits
|
||||||
|
|
||||||
Provide FrameBridge-0.3.1.deb, its exact corresponding FrameBridge source archive, both dependency-source assets, R2 supplement and retained notices through actual working download paths. Verify file hashes at staging and public delivery. Private collection or a future URL is not public availability.
|
Provide all three FrameBridge 0.3.4 distribution-profile packages, their exact corresponding FrameBridge-0.3.4-source.tar.gz and SOURCE-ARCHIVE-MANIFEST.json, both dependency-source assets, R2 supplement and retained notices through actual working download paths. Verify file hashes at staging and public delivery. Private collection or a future URL is not public availability.
|
||||||
|
|
||||||
The unchanged Certifi arrangement retains its exact source assets, original notice, full MPL-2.0 text and recipient access instructions. The original historical Mozilla certdata revision remains unidentified. No independent native-wheel rebuild is claimed. These provenance/reproducibility limits remain explicit.
|
The unchanged Certifi arrangement retains its exact source assets, original notice, full MPL-2.0 text and recipient access instructions. The original historical Mozilla certdata revision remains unidentified. No independent native-wheel rebuild is claimed. These provenance/reproducibility limits remain explicit.
|
||||||
|
|
||||||
|
|||||||
@@ -1,5 +1,6 @@
|
|||||||
{
|
{
|
||||||
"schema_version": 4,
|
"schema_version": 4,
|
||||||
|
"historical_snapshot_notice": "This classification snapshot retains its original counts, hashes and version. The matching release SOURCE-ARCHIVE-MANIFEST.json identifies the complete current source set; historical path classifications do not prove ownership.",
|
||||||
"project_license": "GPL-3.0-only",
|
"project_license": "GPL-3.0-only",
|
||||||
"basis": "Owner decision for original FrameBridge material the rightsholders are entitled to license.",
|
"basis": "Owner decision for original FrameBridge material the rightsholders are entitled to license.",
|
||||||
"scope_notice": "../LICENSING.md",
|
"scope_notice": "../LICENSING.md",
|
||||||
|
|||||||
+3
-3
@@ -1,9 +1,9 @@
|
|||||||
# Sources accompanying FrameBridge 0.3.1
|
# Sources accompanying FrameBridge 0.3.4
|
||||||
|
|
||||||
The matching release set is intended to be delivered together through the project download area. This record identifies the required assets; it does not assert that external access has already been opened.
|
The matching release set is intended to be delivered together through the project download area. This record identifies the required assets; it does not assert that external access has already been opened.
|
||||||
|
|
||||||
- FrameBridge-0.3.1.deb, Debian version 0.3.1.
|
- FrameBridge-0.3.4-debian13-amd64-py313.deb, FrameBridge-0.3.4-ubuntu24.04-amd64-py312.deb and FrameBridge-0.3.4-mint22-amd64-py312.deb; Debian package version 0.3.4.
|
||||||
- FrameBridge-0.3.1-source.tar.gz: the corresponding FrameBridge implementation, build scripts, tests and legal records.
|
- FrameBridge-0.3.4-source.tar.gz and its matching SOURCE-ARCHIVE-MANIFEST.json: the corresponding FrameBridge implementation, reviewed cp313 and cp312 vendor inputs, build scripts, tests and legal records.
|
||||||
- FrameBridge-0.3.1-Community-Preview1-dependency-sources.tar.gz: immutable shared Python/Rust dependency source asset, 82,606,998 bytes, SHA-256 64540a85bd65eac3f394d8c0a967cacbc00e112676d57d644dcd1bb691c1926a. The historical filename is deliberately retained; verify bytes rather than inferring the current project version from that name.
|
- FrameBridge-0.3.1-Community-Preview1-dependency-sources.tar.gz: immutable shared Python/Rust dependency source asset, 82,606,998 bytes, SHA-256 64540a85bd65eac3f394d8c0a967cacbc00e112676d57d644dcd1bb691c1926a. The historical filename is deliberately retained; verify bytes rather than inferring the current project version from that name.
|
||||||
- FrameBridge-0.3.1-tunnel-client-dependency-sources.tar.gz: exact source module archives for the 47 Go dependencies embedded in the retained OpenAI tunnel executable, plus retained notices and provenance records. Its release hash is recorded in the adjacent release checksum manifest and TUNNEL-DEPENDENCY-SOURCES.json.
|
- FrameBridge-0.3.1-tunnel-client-dependency-sources.tar.gz: exact source module archives for the 47 Go dependencies embedded in the retained OpenAI tunnel executable, plus retained notices and provenance records. Its release hash is recorded in the adjacent release checksum manifest and TUNNEL-DEPENDENCY-SOURCES.json.
|
||||||
|
|
||||||
|
|||||||
@@ -1,12 +1,12 @@
|
|||||||
{
|
{
|
||||||
"product": "FrameBridge",
|
"product": "FrameBridge",
|
||||||
"version": "0.3.3",
|
"version": "0.3.4",
|
||||||
"guide_schema": 1,
|
"guide_schema": 1,
|
||||||
"topics": {
|
"topics": {
|
||||||
"start": {
|
"start": {
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"product": "FrameBridge",
|
"product": "FrameBridge",
|
||||||
"version": "0.3.3",
|
"version": "0.3.4",
|
||||||
"guide_schema": 1,
|
"guide_schema": 1,
|
||||||
"topic": "start",
|
"topic": "start",
|
||||||
"title": "Start with FrameBridge",
|
"title": "Start with FrameBridge",
|
||||||
@@ -24,7 +24,6 @@
|
|||||||
"heading": "Install and connect",
|
"heading": "Install and connect",
|
||||||
"body": "Install the package built for your exact Debian 13, Ubuntu 24.04 or Linux Mint 22.x amd64 profile. These are the three release profiles; other distributions and architectures are outside this release. Keep the distribution system Python: 3.13 on Debian 13, 3.12 on Ubuntu 24.04 and Mint 22.x. Use the matching signed APT suite: trixie, noble or mint22. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.",
|
"body": "Install the package built for your exact Debian 13, Ubuntu 24.04 or Linux Mint 22.x amd64 profile. These are the three release profiles; other distributions and architectures are outside this release. Keep the distribution system Python: 3.13 on Debian 13, 3.12 on Ubuntu 24.04 and Mint 22.x. Use the matching signed APT suite: trixie, noble or mint22. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.",
|
||||||
"commands": [
|
"commands": [
|
||||||
"sudo apt install ./framebridge-expanded_0.3.3_amd64.deb",
|
|
||||||
"fb connect"
|
"fb connect"
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
@@ -64,12 +63,12 @@
|
|||||||
],
|
],
|
||||||
"read_only": true,
|
"read_only": true,
|
||||||
"capabilities_verified": false,
|
"capabilities_verified": false,
|
||||||
"guide_sha256": "23abd7eec3efb77ca160c97fec9b8bacc7040419946e75584ed563a509577a57"
|
"guide_sha256": "e2e7a61e9ba53021c155f3fc4d8ffad95ffbdb6e5ac253b171b6ce21a5dd42b4"
|
||||||
},
|
},
|
||||||
"commands": {
|
"commands": {
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"product": "FrameBridge",
|
"product": "FrameBridge",
|
||||||
"version": "0.3.3",
|
"version": "0.3.4",
|
||||||
"guide_schema": 1,
|
"guide_schema": 1,
|
||||||
"topic": "commands",
|
"topic": "commands",
|
||||||
"title": "Command reference",
|
"title": "Command reference",
|
||||||
@@ -86,6 +85,7 @@
|
|||||||
"fb status boot",
|
"fb status boot",
|
||||||
"fb status console",
|
"fb status console",
|
||||||
"fb doctor",
|
"fb doctor",
|
||||||
|
"fb health",
|
||||||
"fb setup",
|
"fb setup",
|
||||||
"fb console",
|
"fb console",
|
||||||
"fb help"
|
"fb help"
|
||||||
@@ -136,12 +136,12 @@
|
|||||||
],
|
],
|
||||||
"read_only": true,
|
"read_only": true,
|
||||||
"capabilities_verified": false,
|
"capabilities_verified": false,
|
||||||
"guide_sha256": "432ab37e7249793cbe72e42d27582d70c2d2c1394ac1f5418b5d3e211e6a7c06"
|
"guide_sha256": "d218df5cdc9e9053f461e4a3807e5e9fa45b6194e4b45bf05b6fc2e6258d5d0d"
|
||||||
},
|
},
|
||||||
"connection": {
|
"connection": {
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"product": "FrameBridge",
|
"product": "FrameBridge",
|
||||||
"version": "0.3.3",
|
"version": "0.3.4",
|
||||||
"guide_schema": 1,
|
"guide_schema": 1,
|
||||||
"topic": "connection",
|
"topic": "connection",
|
||||||
"title": "Connect and disconnect ChatGPT",
|
"title": "Connect and disconnect ChatGPT",
|
||||||
@@ -190,12 +190,12 @@
|
|||||||
],
|
],
|
||||||
"read_only": true,
|
"read_only": true,
|
||||||
"capabilities_verified": false,
|
"capabilities_verified": false,
|
||||||
"guide_sha256": "c41d5c436a7039cfacd9cde4933e24c9f7d6235d43e2e9f4fe106f1a4c631764"
|
"guide_sha256": "418bad3914a250d4c734e0d0a60fcbfcd7e52cd6c5d4dfacc9da236cc4d45e53"
|
||||||
},
|
},
|
||||||
"lifecycle": {
|
"lifecycle": {
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"product": "FrameBridge",
|
"product": "FrameBridge",
|
||||||
"version": "0.3.3",
|
"version": "0.3.4",
|
||||||
"guide_schema": 1,
|
"guide_schema": 1,
|
||||||
"topic": "lifecycle",
|
"topic": "lifecycle",
|
||||||
"title": "Services, connection intent and boot policy",
|
"title": "Services, connection intent and boot policy",
|
||||||
@@ -256,12 +256,12 @@
|
|||||||
],
|
],
|
||||||
"read_only": true,
|
"read_only": true,
|
||||||
"capabilities_verified": false,
|
"capabilities_verified": false,
|
||||||
"guide_sha256": "084358c9d1d41e0639b49d01c7e40b613127e3ead77e156cc2624850c7ebdb16"
|
"guide_sha256": "943322bb685d2dd37fd306bff8b6aed6c85fb54f95af95b986c3448a45dd96b7"
|
||||||
},
|
},
|
||||||
"nodes": {
|
"nodes": {
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"product": "FrameBridge",
|
"product": "FrameBridge",
|
||||||
"version": "0.3.3",
|
"version": "0.3.4",
|
||||||
"guide_schema": 1,
|
"guide_schema": 1,
|
||||||
"topic": "nodes",
|
"topic": "nodes",
|
||||||
"title": "Central and node operation",
|
"title": "Central and node operation",
|
||||||
@@ -285,7 +285,7 @@
|
|||||||
},
|
},
|
||||||
{
|
{
|
||||||
"heading": "Targets",
|
"heading": "Targets",
|
||||||
"body": "LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty --node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.",
|
"body": "LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Fleet results include requested_target, resolved_target, node_id, hostname and transport from the confirmed descriptor. The compatibility target field can remain LOCAL; resolved_target names the actual local computer. Unknown targets never fall back to LOCAL. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty --node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.",
|
||||||
"commands": []
|
"commands": []
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
@@ -310,12 +310,12 @@
|
|||||||
],
|
],
|
||||||
"read_only": true,
|
"read_only": true,
|
||||||
"capabilities_verified": false,
|
"capabilities_verified": false,
|
||||||
"guide_sha256": "ec2adb6ba2cb36e3747bcb4975a6b777ad88d4fe2b9b1cfb1a2f6ec1e8dab43a"
|
"guide_sha256": "79f6875d2d2486557092cbc5e5a4888f8661f00eddb13d93437737893eb343a5"
|
||||||
},
|
},
|
||||||
"terminals": {
|
"terminals": {
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"product": "FrameBridge",
|
"product": "FrameBridge",
|
||||||
"version": "0.3.3",
|
"version": "0.3.4",
|
||||||
"guide_schema": 1,
|
"guide_schema": 1,
|
||||||
"topic": "terminals",
|
"topic": "terminals",
|
||||||
"title": "Persistent Bash terminals",
|
"title": "Persistent Bash terminals",
|
||||||
@@ -376,12 +376,12 @@
|
|||||||
],
|
],
|
||||||
"read_only": true,
|
"read_only": true,
|
||||||
"capabilities_verified": false,
|
"capabilities_verified": false,
|
||||||
"guide_sha256": "0aba231493d9ecae071ecdf5197440e0714393364948079fc4d163ff70cc67e3"
|
"guide_sha256": "41e9e1c93bb6c8cc2d84c55d33d70d71693ddf835b5d4c199810db59af932139"
|
||||||
},
|
},
|
||||||
"screens": {
|
"screens": {
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"product": "FrameBridge",
|
"product": "FrameBridge",
|
||||||
"version": "0.3.3",
|
"version": "0.3.4",
|
||||||
"guide_schema": 1,
|
"guide_schema": 1,
|
||||||
"topic": "screens",
|
"topic": "screens",
|
||||||
"title": "Authentic screen observation and input",
|
"title": "Authentic screen observation and input",
|
||||||
@@ -431,12 +431,12 @@
|
|||||||
],
|
],
|
||||||
"read_only": true,
|
"read_only": true,
|
||||||
"capabilities_verified": false,
|
"capabilities_verified": false,
|
||||||
"guide_sha256": "eeaf9cfed9e7a84d59a727c4388b0869b02a6ed870647e87b333d318a3584c9a"
|
"guide_sha256": "506c7fcba592ccc473774a809871871285a199e8a8f72b9e230eb23481fd8a85"
|
||||||
},
|
},
|
||||||
"diagnostics": {
|
"diagnostics": {
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"product": "FrameBridge",
|
"product": "FrameBridge",
|
||||||
"version": "0.3.3",
|
"version": "0.3.4",
|
||||||
"guide_schema": 1,
|
"guide_schema": 1,
|
||||||
"topic": "diagnostics",
|
"topic": "diagnostics",
|
||||||
"title": "Status and diagnosis",
|
"title": "Status and diagnosis",
|
||||||
@@ -453,11 +453,19 @@
|
|||||||
},
|
},
|
||||||
{
|
{
|
||||||
"heading": "Doctor",
|
"heading": "Doctor",
|
||||||
"body": "doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes. Candidate eligibility checks the exact OS release, amd64 architecture, package profile and CPython ABI before starting native components. Debian 13/LMDE 7 use cp313, Ubuntu 24.04/Mint 22.x use cp312, and Ubuntu 26.04 uses cp314. A matching profile does not establish a tested installation; never repair an ABI mismatch by replacing system Python or weakening package dependencies.",
|
"body": "doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes. Eligibility checks the exact OS release, amd64 architecture, package profile and CPython ABI before starting native components. The published 0.3.3 scope is Debian 13 with cp313 and Ubuntu 24.04/Mint 22.x with cp312. LMDE 7 and Ubuntu 26.04 builder experiments remain outside that validated scope. A matching profile or a successful development build does not establish a tested installation; never repair an ABI mismatch by replacing system Python or weakening package dependencies.",
|
||||||
"commands": [
|
"commands": [
|
||||||
"fb doctor"
|
"fb doctor"
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
"heading": "Local health summary",
|
||||||
|
"body": "health combines this local profile's existing status and prerequisite observations into an allowlisted report. It identifies LOCAL as this computer and reports the profile, role, connection intent, local tools, boot policy and desktop availability. It never starts, repairs, connects, changes boot policy or creates an absent profile. It does not scan the fleet or probe terminal commands, screen capture or input. States are healthy, paused, degraded, unavailable and unconfigured. An intentional connection pause can be healthy; missing information cannot. JSON result.ok describes observation completeness; result.health.healthy describes health. Health exits 0 for a complete healthy or intentionally paused observation and 1 for degraded, unavailable or unconfigured state. The CLI version is not proof of the running version. Detailed troubleshooting remains local in status and doctor.",
|
||||||
|
"commands": [
|
||||||
|
"fb health",
|
||||||
|
"fb --json health"
|
||||||
|
]
|
||||||
|
},
|
||||||
{
|
{
|
||||||
"heading": "Logs and progress",
|
"heading": "Logs and progress",
|
||||||
"body": "Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.",
|
"body": "Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.",
|
||||||
@@ -481,12 +489,12 @@
|
|||||||
],
|
],
|
||||||
"read_only": true,
|
"read_only": true,
|
||||||
"capabilities_verified": false,
|
"capabilities_verified": false,
|
||||||
"guide_sha256": "77a65897aacfeaa2b06dd184ac78d366d28980847b0cbdd1429c889e0e2898a6"
|
"guide_sha256": "6f91c71b82e945767d98f113ae1b958f2222939bf94c0657d1ada047b43d6932"
|
||||||
},
|
},
|
||||||
"security": {
|
"security": {
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"product": "FrameBridge",
|
"product": "FrameBridge",
|
||||||
"version": "0.3.3",
|
"version": "0.3.4",
|
||||||
"guide_schema": 1,
|
"guide_schema": 1,
|
||||||
"topic": "security",
|
"topic": "security",
|
||||||
"title": "Authorization, distribution and safe operation",
|
"title": "Authorization, distribution and safe operation",
|
||||||
@@ -521,12 +529,12 @@
|
|||||||
],
|
],
|
||||||
"read_only": true,
|
"read_only": true,
|
||||||
"capabilities_verified": false,
|
"capabilities_verified": false,
|
||||||
"guide_sha256": "f257fcbbdec39395a15655b0a5123fb385ce7eaba2a256de07a5da65eab3ec8e"
|
"guide_sha256": "0b7c6e55958911306a71f0d0ea5a504df7b1447967b424b5e8a03b4b53275211"
|
||||||
},
|
},
|
||||||
"compatibility": {
|
"compatibility": {
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"product": "FrameBridge",
|
"product": "FrameBridge",
|
||||||
"version": "0.3.3",
|
"version": "0.3.4",
|
||||||
"guide_schema": 1,
|
"guide_schema": 1,
|
||||||
"topic": "compatibility",
|
"topic": "compatibility",
|
||||||
"title": "Compatibility with earlier commands",
|
"title": "Compatibility with earlier commands",
|
||||||
@@ -569,8 +577,8 @@
|
|||||||
],
|
],
|
||||||
"read_only": true,
|
"read_only": true,
|
||||||
"capabilities_verified": false,
|
"capabilities_verified": false,
|
||||||
"guide_sha256": "9056f77b27f326bebfdbb54dd10b748d6315797b07afe1aee29f42d6210dae36"
|
"guide_sha256": "970ed8c5f509e78adc6fd9d99fd14a3edc93fc597184e9de54723763d7807544"
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"guide_sha256": "5dc6ed2744e53d7d2ce1f471e2ab94d50f9c52f83ae85abe495bacad34b1b96c"
|
"guide_sha256": "aecf94c39b17d53be24aecd67089ed5cfa52e3b0499e6a615b3a4e04cfb6e319"
|
||||||
}
|
}
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
# FrameBridge — command guide
|
# FrameBridge — command guide
|
||||||
|
|
||||||
Version: 0.3.3 | Guide schema: 1
|
Version: 0.3.4 | Guide schema: 1
|
||||||
|
|
||||||
This reference is generated from the shared CLI/MCP guide. Use the matching installed version.
|
This reference is generated from the shared CLI/MCP guide. Use the matching installed version.
|
||||||
|
|
||||||
@@ -36,7 +36,6 @@ fb --json status
|
|||||||
Install the package built for your exact Debian 13, Ubuntu 24.04 or Linux Mint 22.x amd64 profile. These are the three release profiles; other distributions and architectures are outside this release. Keep the distribution system Python: 3.13 on Debian 13, 3.12 on Ubuntu 24.04 and Mint 22.x. Use the matching signed APT suite: trixie, noble or mint22. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.
|
Install the package built for your exact Debian 13, Ubuntu 24.04 or Linux Mint 22.x amd64 profile. These are the three release profiles; other distributions and architectures are outside this release. Keep the distribution system Python: 3.13 on Debian 13, 3.12 on Ubuntu 24.04 and Mint 22.x. Use the matching signed APT suite: trixie, noble or mint22. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.
|
||||||
|
|
||||||
~~~sh
|
~~~sh
|
||||||
sudo apt install ./framebridge-expanded_0.3.3_amd64.deb
|
|
||||||
fb connect
|
fb connect
|
||||||
~~~
|
~~~
|
||||||
|
|
||||||
@@ -80,6 +79,7 @@ fb status runtime
|
|||||||
fb status boot
|
fb status boot
|
||||||
fb status console
|
fb status console
|
||||||
fb doctor
|
fb doctor
|
||||||
|
fb health
|
||||||
fb setup
|
fb setup
|
||||||
fb console
|
fb console
|
||||||
fb help
|
fb help
|
||||||
@@ -231,7 +231,7 @@ fb nodes status
|
|||||||
|
|
||||||
### Targets
|
### Targets
|
||||||
|
|
||||||
LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty --node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.
|
LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Fleet results include requested_target, resolved_target, node_id, hostname and transport from the confirmed descriptor. The compatibility target field can remain LOCAL; resolved_target names the actual local computer. Unknown targets never fall back to LOCAL. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty --node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.
|
||||||
|
|
||||||
### Transport trust
|
### Transport trust
|
||||||
|
|
||||||
@@ -344,12 +344,21 @@ fb status boot
|
|||||||
|
|
||||||
### Doctor
|
### Doctor
|
||||||
|
|
||||||
doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes. Candidate eligibility checks the exact OS release, amd64 architecture, package profile and CPython ABI before starting native components. Debian 13/LMDE 7 use cp313, Ubuntu 24.04/Mint 22.x use cp312, and Ubuntu 26.04 uses cp314. A matching profile does not establish a tested installation; never repair an ABI mismatch by replacing system Python or weakening package dependencies.
|
doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes. Eligibility checks the exact OS release, amd64 architecture, package profile and CPython ABI before starting native components. The published 0.3.3 scope is Debian 13 with cp313 and Ubuntu 24.04/Mint 22.x with cp312. LMDE 7 and Ubuntu 26.04 builder experiments remain outside that validated scope. A matching profile or a successful development build does not establish a tested installation; never repair an ABI mismatch by replacing system Python or weakening package dependencies.
|
||||||
|
|
||||||
~~~sh
|
~~~sh
|
||||||
fb doctor
|
fb doctor
|
||||||
~~~
|
~~~
|
||||||
|
|
||||||
|
### Local health summary
|
||||||
|
|
||||||
|
health combines this local profile's existing status and prerequisite observations into an allowlisted report. It identifies LOCAL as this computer and reports the profile, role, connection intent, local tools, boot policy and desktop availability. It never starts, repairs, connects, changes boot policy or creates an absent profile. It does not scan the fleet or probe terminal commands, screen capture or input. States are healthy, paused, degraded, unavailable and unconfigured. An intentional connection pause can be healthy; missing information cannot. JSON result.ok describes observation completeness; result.health.healthy describes health. Health exits 0 for a complete healthy or intentionally paused observation and 1 for degraded, unavailable or unconfigured state. The CLI version is not proof of the running version. Detailed troubleshooting remains local in status and doctor.
|
||||||
|
|
||||||
|
~~~sh
|
||||||
|
fb health
|
||||||
|
fb --json health
|
||||||
|
~~~
|
||||||
|
|
||||||
### Logs and progress
|
### Logs and progress
|
||||||
|
|
||||||
Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.
|
Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# FrameBridge — Debian, Ubuntu and Linux Mint installation and first use
|
# FrameBridge — Debian, Ubuntu and Linux Mint installation and first use
|
||||||
|
|
||||||
Version: 0.3.3 | Guide schema: 1
|
Version: 0.3.4 | Guide schema: 1
|
||||||
|
|
||||||
This reference is generated from the shared CLI/MCP guide. Use the matching installed version.
|
This reference is generated from the shared CLI/MCP guide. Use the matching installed version.
|
||||||
|
|
||||||
@@ -36,7 +36,6 @@ fb --json status
|
|||||||
Install the package built for your exact Debian 13, Ubuntu 24.04 or Linux Mint 22.x amd64 profile. These are the three release profiles; other distributions and architectures are outside this release. Keep the distribution system Python: 3.13 on Debian 13, 3.12 on Ubuntu 24.04 and Mint 22.x. Use the matching signed APT suite: trixie, noble or mint22. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.
|
Install the package built for your exact Debian 13, Ubuntu 24.04 or Linux Mint 22.x amd64 profile. These are the three release profiles; other distributions and architectures are outside this release. Keep the distribution system Python: 3.13 on Debian 13, 3.12 on Ubuntu 24.04 and Mint 22.x. Use the matching signed APT suite: trixie, noble or mint22. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.
|
||||||
|
|
||||||
~~~sh
|
~~~sh
|
||||||
sudo apt install ./framebridge-expanded_0.3.3_amd64.deb
|
|
||||||
fb connect
|
fb connect
|
||||||
~~~
|
~~~
|
||||||
|
|
||||||
@@ -80,6 +79,7 @@ fb status runtime
|
|||||||
fb status boot
|
fb status boot
|
||||||
fb status console
|
fb status console
|
||||||
fb doctor
|
fb doctor
|
||||||
|
fb health
|
||||||
fb setup
|
fb setup
|
||||||
fb console
|
fb console
|
||||||
fb help
|
fb help
|
||||||
@@ -231,7 +231,7 @@ fb nodes status
|
|||||||
|
|
||||||
### Targets
|
### Targets
|
||||||
|
|
||||||
LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty --node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.
|
LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Fleet results include requested_target, resolved_target, node_id, hostname and transport from the confirmed descriptor. The compatibility target field can remain LOCAL; resolved_target names the actual local computer. Unknown targets never fall back to LOCAL. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty --node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.
|
||||||
|
|
||||||
### Transport trust
|
### Transport trust
|
||||||
|
|
||||||
@@ -344,12 +344,21 @@ fb status boot
|
|||||||
|
|
||||||
### Doctor
|
### Doctor
|
||||||
|
|
||||||
doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes. Candidate eligibility checks the exact OS release, amd64 architecture, package profile and CPython ABI before starting native components. Debian 13/LMDE 7 use cp313, Ubuntu 24.04/Mint 22.x use cp312, and Ubuntu 26.04 uses cp314. A matching profile does not establish a tested installation; never repair an ABI mismatch by replacing system Python or weakening package dependencies.
|
doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes. Eligibility checks the exact OS release, amd64 architecture, package profile and CPython ABI before starting native components. The published 0.3.3 scope is Debian 13 with cp313 and Ubuntu 24.04/Mint 22.x with cp312. LMDE 7 and Ubuntu 26.04 builder experiments remain outside that validated scope. A matching profile or a successful development build does not establish a tested installation; never repair an ABI mismatch by replacing system Python or weakening package dependencies.
|
||||||
|
|
||||||
~~~sh
|
~~~sh
|
||||||
fb doctor
|
fb doctor
|
||||||
~~~
|
~~~
|
||||||
|
|
||||||
|
### Local health summary
|
||||||
|
|
||||||
|
health combines this local profile's existing status and prerequisite observations into an allowlisted report. It identifies LOCAL as this computer and reports the profile, role, connection intent, local tools, boot policy and desktop availability. It never starts, repairs, connects, changes boot policy or creates an absent profile. It does not scan the fleet or probe terminal commands, screen capture or input. States are healthy, paused, degraded, unavailable and unconfigured. An intentional connection pause can be healthy; missing information cannot. JSON result.ok describes observation completeness; result.health.healthy describes health. Health exits 0 for a complete healthy or intentionally paused observation and 1 for degraded, unavailable or unconfigured state. The CLI version is not proof of the running version. Detailed troubleshooting remains local in status and doctor.
|
||||||
|
|
||||||
|
~~~sh
|
||||||
|
fb health
|
||||||
|
fb --json health
|
||||||
|
~~~
|
||||||
|
|
||||||
### Logs and progress
|
### Logs and progress
|
||||||
|
|
||||||
Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.
|
Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
.TH FRAMEBRIDGE 1 "2026-10-28" "FrameBridge 0.3.3" "User Commands"
|
.TH FRAMEBRIDGE 1 "2026-10-29" "FrameBridge 0.3.4" "User Commands"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
framebridge, fb \- use local Linux tools and enrolled nodes with ChatGPT
|
framebridge, fb \- use local Linux tools and enrolled nodes with ChatGPT
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
@@ -21,7 +21,6 @@ fb \-\-json status
|
|||||||
Install the package built for your exact Debian 13, Ubuntu 24.04 or Linux Mint 22.x amd64 profile. These are the three release profiles; other distributions and architectures are outside this release. Keep the distribution system Python: 3.13 on Debian 13, 3.12 on Ubuntu 24.04 and Mint 22.x. Use the matching signed APT suite: trixie, noble or mint22. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.
|
Install the package built for your exact Debian 13, Ubuntu 24.04 or Linux Mint 22.x amd64 profile. These are the three release profiles; other distributions and architectures are outside this release. Keep the distribution system Python: 3.13 on Debian 13, 3.12 on Ubuntu 24.04 and Mint 22.x. Use the matching signed APT suite: trixie, noble or mint22. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.
|
||||||
.PP
|
.PP
|
||||||
.nf
|
.nf
|
||||||
sudo apt install ./framebridge\-expanded_0.3.3_amd64.deb
|
|
||||||
fb connect
|
fb connect
|
||||||
.fi
|
.fi
|
||||||
.SS Updating and removal
|
.SS Updating and removal
|
||||||
@@ -53,6 +52,7 @@ fb status runtime
|
|||||||
fb status boot
|
fb status boot
|
||||||
fb status console
|
fb status console
|
||||||
fb doctor
|
fb doctor
|
||||||
|
fb health
|
||||||
fb setup
|
fb setup
|
||||||
fb console
|
fb console
|
||||||
fb help
|
fb help
|
||||||
@@ -162,7 +162,7 @@ fb nodes pending
|
|||||||
fb nodes status
|
fb nodes status
|
||||||
.fi
|
.fi
|
||||||
.SS Targets
|
.SS Targets
|
||||||
LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty \-\-node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.
|
LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Fleet results include requested_target, resolved_target, node_id, hostname and transport from the confirmed descriptor. The compatibility target field can remain LOCAL; resolved_target names the actual local computer. Unknown targets never fall back to LOCAL. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty \-\-node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.
|
||||||
.SS Transport trust
|
.SS Transport trust
|
||||||
certificates create manages a private central/node transport CA, not a public website certificate or ChatGPT account authentication. Private keys stay protected on the central host; distribute only the required public trust material. Off\-loopback broker use requires correctly configured verified TLS. Do not recreate trust merely to work around a connection symptom.
|
certificates create manages a private central/node transport CA, not a public website certificate or ChatGPT account authentication. Private keys stay protected on the central host; distribute only the required public trust material. Off\-loopback broker use requires correctly configured verified TLS. Do not recreate trust merely to work around a connection symptom.
|
||||||
.PP
|
.PP
|
||||||
@@ -237,11 +237,18 @@ fb status runtime
|
|||||||
fb status boot
|
fb status boot
|
||||||
.fi
|
.fi
|
||||||
.SS Doctor
|
.SS Doctor
|
||||||
doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes. Candidate eligibility checks the exact OS release, amd64 architecture, package profile and CPython ABI before starting native components. Debian 13/LMDE 7 use cp313, Ubuntu 24.04/Mint 22.x use cp312, and Ubuntu 26.04 uses cp314. A matching profile does not establish a tested installation; never repair an ABI mismatch by replacing system Python or weakening package dependencies.
|
doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes. Eligibility checks the exact OS release, amd64 architecture, package profile and CPython ABI before starting native components. The published 0.3.3 scope is Debian 13 with cp313 and Ubuntu 24.04/Mint 22.x with cp312. LMDE 7 and Ubuntu 26.04 builder experiments remain outside that validated scope. A matching profile or a successful development build does not establish a tested installation; never repair an ABI mismatch by replacing system Python or weakening package dependencies.
|
||||||
.PP
|
.PP
|
||||||
.nf
|
.nf
|
||||||
fb doctor
|
fb doctor
|
||||||
.fi
|
.fi
|
||||||
|
.SS Local health summary
|
||||||
|
health combines this local profile's existing status and prerequisite observations into an allowlisted report. It identifies LOCAL as this computer and reports the profile, role, connection intent, local tools, boot policy and desktop availability. It never starts, repairs, connects, changes boot policy or creates an absent profile. It does not scan the fleet or probe terminal commands, screen capture or input. States are healthy, paused, degraded, unavailable and unconfigured. An intentional connection pause can be healthy; missing information cannot. JSON result.ok describes observation completeness; result.health.healthy describes health. Health exits 0 for a complete healthy or intentionally paused observation and 1 for degraded, unavailable or unconfigured state. The CLI version is not proof of the running version. Detailed troubleshooting remains local in status and doctor.
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
fb health
|
||||||
|
fb \-\-json health
|
||||||
|
.fi
|
||||||
.SS Logs and progress
|
.SS Logs and progress
|
||||||
Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.
|
Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.
|
||||||
.PP
|
.PP
|
||||||
|
|||||||
@@ -1 +1 @@
|
|||||||
__version__ = "0.3.3"
|
__version__ = "0.3.4"
|
||||||
@@ -132,6 +132,39 @@ def _prune_helpers(state, keep=()):
|
|||||||
_command(["sudo", "-n", "--", str(HELPER), "prune", _profile_id(state), ",".join(values) or "-"])
|
_command(["sudo", "-n", "--", str(HELPER), "prune", _profile_id(state), ",".join(values) or "-"])
|
||||||
|
|
||||||
|
|
||||||
|
def _node_helper_cleanup_required(state):
|
||||||
|
"""Only omit privileged cleanup when no managed grant can authorize it.
|
||||||
|
|
||||||
|
The encrypted registry is deliberately private to root. Its orphaned
|
||||||
|
ciphertext does not grant access without a matching sudo policy. Inspect
|
||||||
|
only policy names in the secured, root-owned policy directory; never read
|
||||||
|
rule contents or treat a failed/incomplete inspection as an empty registry.
|
||||||
|
"""
|
||||||
|
from .credential_helper import SUDOERS, _root_path
|
||||||
|
_helper_ready()
|
||||||
|
uid, profile = str(os.getuid()), _profile_id(state)
|
||||||
|
prefixes = ("framebridge-credential-" + uid + "-" + profile + "-",
|
||||||
|
"framebridge-credential-authorize-" + uid + "-" + profile + "-")
|
||||||
|
patterns = (re.escape(prefixes[0]) + r"[0-9a-f]{64}",
|
||||||
|
re.escape(prefixes[1]) + r"(?:host|user)")
|
||||||
|
try:
|
||||||
|
directory = _root_path(SUDOERS, directory=True)
|
||||||
|
names = [path.name for path in directory.iterdir()]
|
||||||
|
except (OSError, RuntimeError):
|
||||||
|
return True
|
||||||
|
cleanup_required = False
|
||||||
|
for name in names:
|
||||||
|
if any(re.fullmatch(pattern, name) for pattern in patterns):
|
||||||
|
cleanup_required = True
|
||||||
|
continue
|
||||||
|
# A malformed entry in this exact owner's/profile's managed namespace
|
||||||
|
# is ambiguous. The helper's normal cleanup does not recognize every
|
||||||
|
# malformed authorization name, so require explicit review instead.
|
||||||
|
if name.startswith(prefixes):
|
||||||
|
raise RuntimeError("An ambiguous managed credential policy needs administrator review before node startup can be configured.")
|
||||||
|
return cleanup_required
|
||||||
|
|
||||||
|
|
||||||
@contextmanager
|
@contextmanager
|
||||||
def _credential_transaction(state, encrypted, backend):
|
def _credential_transaction(state, encrypted, backend):
|
||||||
transaction = {"committed": False}
|
transaction = {"committed": False}
|
||||||
@@ -270,10 +303,17 @@ def _check_unit_directory(path):
|
|||||||
for directory in [Path.home() / ".config", Path.home() / ".config/systemd", path.parent]:
|
for directory in [Path.home() / ".config", Path.home() / ".config/systemd", path.parent]:
|
||||||
if directory.is_symlink():
|
if directory.is_symlink():
|
||||||
raise RuntimeError("User service directories must not be symbolic links.")
|
raise RuntimeError("User service directories must not be symbolic links.")
|
||||||
directory.mkdir(mode=0o700, exist_ok=True)
|
try:
|
||||||
info = directory.stat()
|
directory.mkdir(mode=0o700, exist_ok=True)
|
||||||
if info.st_uid != os.getuid() or info.st_mode & 0o022:
|
except PermissionError:
|
||||||
raise RuntimeError("User service directories must be owned by this user and not writable by others.")
|
raise RuntimeError("This account cannot create its user service directory; existing ownership and permissions were left unchanged.") from None
|
||||||
|
info = directory.lstat()
|
||||||
|
# Service accounts can have administrator-owned .config ancestors.
|
||||||
|
# Those ancestors are safe when immutable to other accounts; the
|
||||||
|
# directory containing the unit must still belong to this owner.
|
||||||
|
allowed_owner = info.st_uid == os.getuid() or (directory != path.parent and info.st_uid == 0)
|
||||||
|
if not stat.S_ISDIR(info.st_mode) or not allowed_owner or info.st_mode & 0o022:
|
||||||
|
raise RuntimeError("User service directories must have a safe owner and not be writable by others; the final directory must belong to this user.")
|
||||||
|
|
||||||
|
|
||||||
def _manifest(directory):
|
def _manifest(directory):
|
||||||
@@ -653,9 +693,15 @@ def _enable(state, *, start_now=True, confirm=True):
|
|||||||
_check_unit_directory(unit)
|
_check_unit_directory(unit)
|
||||||
if unit.exists() or unit.is_symlink() or (directory / "credential.cred").exists() or (directory / "credential.cred").is_symlink():
|
if unit.exists() or unit.is_symlink() or (directory / "credential.cred").exists() or (directory / "credential.cred").is_symlink():
|
||||||
raise RuntimeError("Existing unowned service or encrypted credential; nothing was replaced.")
|
raise RuntimeError("Existing unowned service or encrypted credential; nothing was replaced.")
|
||||||
_command(["sudo", "-v"], timeout=180)
|
|
||||||
user = pwd.getpwuid(os.getuid()).pw_name
|
user = pwd.getpwuid(os.getuid()).pw_name
|
||||||
linger_before = _linger(user)
|
linger_before = _linger(user)
|
||||||
|
helper_cleanup_required = (node and _helper_present() and
|
||||||
|
(not linger_before or _node_helper_cleanup_required(state)))
|
||||||
|
# An administrator may already have enabled this node owner's user
|
||||||
|
# services at boot. Installing its own unit then needs no new privilege.
|
||||||
|
# Central profiles still authenticate before protecting connection input.
|
||||||
|
if not node or not linger_before or helper_cleanup_required:
|
||||||
|
_command(["sudo", "-v"], timeout=180)
|
||||||
units_before = _enabled_units()
|
units_before = _enabled_units()
|
||||||
encrypted = b""
|
encrypted = b""
|
||||||
print("[2/3] Preparing this node..." if node else "[2/3] Protecting the connection key...", flush=True)
|
print("[2/3] Preparing this node..." if node else "[2/3] Protecting the connection key...", flush=True)
|
||||||
@@ -672,7 +718,7 @@ def _enable(state, *, start_now=True, confirm=True):
|
|||||||
runtime_key = ""
|
runtime_key = ""
|
||||||
if len(encrypted) < 80 or len(encrypted) > 131072:
|
if len(encrypted) < 80 or len(encrypted) > 131072:
|
||||||
raise RuntimeError("Credential encryption returned an invalid result.")
|
raise RuntimeError("Credential encryption returned an invalid result.")
|
||||||
elif _helper_present():
|
elif helper_cleanup_required:
|
||||||
_prune_helpers(state)
|
_prune_helpers(state)
|
||||||
with _credential_transaction(state, encrypted, backend) as transaction:
|
with _credential_transaction(state, encrypted, backend) as transaction:
|
||||||
blob = directory / "credential.cred"
|
blob = directory / "credential.cred"
|
||||||
@@ -693,7 +739,8 @@ def _enable(state, *, start_now=True, confirm=True):
|
|||||||
record["changed_config_sha256"] = hashlib.sha256(_read(state / "config.json")).hexdigest()
|
record["changed_config_sha256"] = hashlib.sha256(_read(state / "config.json")).hexdigest()
|
||||||
_json(directory / "installation.json", record); created.append(directory / "installation.json")
|
_json(directory / "installation.json", record); created.append(directory / "installation.json")
|
||||||
print("[3/3] Enabling automatic startup...", flush=True)
|
print("[3/3] Enabling automatic startup...", flush=True)
|
||||||
_command(["sudo", "-n", "--", "loginctl", "enable-linger", user])
|
if not node or not linger_before:
|
||||||
|
_command(["sudo", "-n", "--", "loginctl", "enable-linger", user])
|
||||||
_systemctl("daemon-reload")
|
_systemctl("daemon-reload")
|
||||||
if start_now:
|
if start_now:
|
||||||
_systemctl("enable", "--now", unit.name)
|
_systemctl("enable", "--now", unit.name)
|
||||||
@@ -946,7 +993,17 @@ def _connection_action(state, action):
|
|||||||
|
|
||||||
|
|
||||||
def _worker_status(directory, name):
|
def _worker_status(directory, name):
|
||||||
_json(directory / "worker-status.json", {"state": name, "updated_at": time.time()}, replace=True)
|
path = directory / "worker-status.json"
|
||||||
|
try:
|
||||||
|
previous = json.loads(_read(path))
|
||||||
|
except (FileNotFoundError, ValueError):
|
||||||
|
previous = None
|
||||||
|
# This is a transition timestamp, not a liveness heartbeat. systemd and the
|
||||||
|
# owned process identity report liveness separately. Avoid a durable fsync
|
||||||
|
# every two seconds while the worker remains in the same state.
|
||||||
|
if isinstance(previous, dict) and previous.get("state") == name:
|
||||||
|
return
|
||||||
|
_json(path, {"state": name, "updated_at": time.time()}, replace=True)
|
||||||
|
|
||||||
|
|
||||||
def worker(state):
|
def worker(state):
|
||||||
|
|||||||
@@ -451,6 +451,18 @@ def _doctor_command(args, state):
|
|||||||
return _result_code(value)
|
return _result_code(value)
|
||||||
|
|
||||||
|
|
||||||
|
def _health_command(args, state):
|
||||||
|
health = _module("health")
|
||||||
|
value = health.collect(state)
|
||||||
|
if args.json:
|
||||||
|
_show(value)
|
||||||
|
else:
|
||||||
|
print(health.render(value))
|
||||||
|
# Query success and operational health are deliberately separate. An
|
||||||
|
# intentional pause can be healthy; missing/unknown state cannot pass.
|
||||||
|
return 0 if value.get("ok") is True and value.get("health", {}).get("healthy") is True else 1
|
||||||
|
|
||||||
|
|
||||||
def _service_command(args, state):
|
def _service_command(args, state):
|
||||||
action = args.service_action
|
action = args.service_action
|
||||||
lifecycle = _module("lifecycle")
|
lifecycle = _module("lifecycle")
|
||||||
@@ -540,6 +552,7 @@ def build_parser():
|
|||||||
status = sub.add_parser("status", help="Observe local tools, ChatGPT connection and startup policy without changing them.")
|
status = sub.add_parser("status", help="Observe local tools, ChatGPT connection and startup policy without changing them.")
|
||||||
status.add_argument("scope", nargs="?", choices=("connection", "runtime", "boot", "console"))
|
status.add_argument("scope", nargs="?", choices=("connection", "runtime", "boot", "console"))
|
||||||
sub.add_parser("doctor", help="Diagnose prerequisites and problems; does not repair or connect.")
|
sub.add_parser("doctor", help="Diagnose prerequisites and problems; does not repair or connect.")
|
||||||
|
sub.add_parser("health", help="Read one local profile's health, identity and prerequisites; no repair or connection.")
|
||||||
sub.add_parser("setup", help="Optional advanced role/profile setup; does not start services or connect.")
|
sub.add_parser("setup", help="Optional advanced role/profile setup; does not start services or connect.")
|
||||||
help_parser = sub.add_parser("help", help="Read the installed, versioned English guide.")
|
help_parser = sub.add_parser("help", help="Read the installed, versioned English guide.")
|
||||||
help_parser.add_argument("topic", nargs="?", default="start", help="Guide topic; use all for the complete reference.")
|
help_parser.add_argument("topic", nargs="?", default="start", help="Guide topic; use all for the complete reference.")
|
||||||
@@ -665,14 +678,14 @@ def _dispatch(parser, args):
|
|||||||
return _help_command(argparse.Namespace(command="help", topic="start", json=True, non_interactive=True))
|
return _help_command(argparse.Namespace(command="help", topic="start", json=True, non_interactive=True))
|
||||||
parser.print_help()
|
parser.print_help()
|
||||||
return 0
|
return 0
|
||||||
print("FrameBridge\n1. Connect\n2. Status\n3. Doctor\n4. Open console\n5. Help\n6. Advanced setup\n0. Exit")
|
print("FrameBridge\n1. Connect\n2. Status\n3. Doctor\n4. Open console\n5. Help\n6. Advanced setup\n7. Health summary\n0. Exit")
|
||||||
try:
|
try:
|
||||||
choice = input("Choose an action: ").strip()
|
choice = input("Choose an action: ").strip()
|
||||||
except (EOFError, KeyboardInterrupt):
|
except (EOFError, KeyboardInterrupt):
|
||||||
print("\nCancelled.", file=sys.stderr)
|
print("\nCancelled.", file=sys.stderr)
|
||||||
return 130
|
return 130
|
||||||
action = {"1":["connect"], "2":["status"], "3":["doctor"], "4":["console"],
|
action = {"1":["connect"], "2":["status"], "3":["doctor"], "4":["console"],
|
||||||
"5":["help"], "6":["setup"]}.get(choice)
|
"5":["help"], "6":["setup"], "7":["health"]}.get(choice)
|
||||||
if choice == "0":
|
if choice == "0":
|
||||||
return 0
|
return 0
|
||||||
if action is None:
|
if action is None:
|
||||||
@@ -712,6 +725,8 @@ def _dispatch(parser, args):
|
|||||||
return _status_command(args, state)
|
return _status_command(args, state)
|
||||||
if args.command == "doctor":
|
if args.command == "doctor":
|
||||||
return _doctor_command(args, state)
|
return _doctor_command(args, state)
|
||||||
|
if args.command == "health":
|
||||||
|
return _health_command(args, state)
|
||||||
if args.command == "service":
|
if args.command == "service":
|
||||||
return _service_command(args, state)
|
return _service_command(args, state)
|
||||||
if args.command == "connection":
|
if args.command == "connection":
|
||||||
|
|||||||
@@ -111,7 +111,7 @@ def assess(prefix, *, os_release=None, machine=None, python_version=None, libc=N
|
|||||||
expected = PROFILES[manifest["profile_id"]]
|
expected = PROFILES[manifest["profile_id"]]
|
||||||
if (manifest.get("architecture"), manifest.get("python_minor"), manifest.get("python_abi")) != ("amd64", expected[2], expected[3]):
|
if (manifest.get("architecture"), manifest.get("python_minor"), manifest.get("python_abi")) != ("amd64", expected[2], expected[3]):
|
||||||
raise ValueError("inconsistent profile ABI")
|
raise ValueError("inconsistent profile ABI")
|
||||||
if manifest.get("validation_status") not in {"candidate", "validated"}:
|
if manifest.get("validation_status") not in {"candidate", "release_build", "validated"}:
|
||||||
raise ValueError("missing validation status")
|
raise ValueError("missing validation status")
|
||||||
if manifest["profile_id"] != selected or manifest["python_minor"] != minor or manifest["python_abi"] != abi:
|
if manifest["profile_id"] != selected or manifest["python_minor"] != minor or manifest["python_abi"] != abi:
|
||||||
issues.append("Installed artifact profile/ABI does not match this operating system and interpreter.")
|
issues.append("Installed artifact profile/ABI does not match this operating system and interpreter.")
|
||||||
@@ -126,7 +126,9 @@ def assess(prefix, *, os_release=None, machine=None, python_version=None, libc=N
|
|||||||
warnings.append("Source checkout has no artifact manifest; only the legacy Debian 13/cp313 profile is eligible.")
|
warnings.append("Source checkout has no artifact manifest; only the legacy Debian 13/cp313 profile is eligible.")
|
||||||
issues.extend(_vendor_issues(prefix, abi))
|
issues.extend(_vendor_issues(prefix, abi))
|
||||||
validation = manifest.get("validation_status") if manifest else "source-unvalidated"
|
validation = manifest.get("validation_status") if manifest else "source-unvalidated"
|
||||||
if validation != "validated":
|
if validation == "release_build":
|
||||||
|
warnings.append("Release assembly does not establish a tested installation on this target; consult the external release acceptance record.")
|
||||||
|
elif validation != "validated":
|
||||||
warnings.append("Candidate compatibility checks do not establish a tested installation on this target.")
|
warnings.append("Candidate compatibility checks do not establish a tested installation on this target.")
|
||||||
return {"ok": not issues, "profile_id": selected, "artifact_profile_id": manifest.get("profile_id") if manifest else None,
|
return {"ok": not issues, "profile_id": selected, "artifact_profile_id": manifest.get("profile_id") if manifest else None,
|
||||||
"architecture": machine, "python_minor": minor, "python_abi": abi, "python_implementation": implementation, "python_abi_flags": abi_flags,
|
"architecture": machine, "python_minor": minor, "python_abi": abi, "python_implementation": implementation, "python_abi_flags": abi_flags,
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
"""Profile-scoped detached ChatGPT supervision without a persistent credential."""
|
"""Profile-scoped detached ChatGPT supervision without a persistent credential."""
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
import fcntl
|
import fcntl
|
||||||
|
import hashlib
|
||||||
import json
|
import json
|
||||||
import os
|
import os
|
||||||
import resource
|
import resource
|
||||||
@@ -17,6 +18,10 @@ from .config import private_dir, state_path
|
|||||||
_BOOTSTRAP = "import sys;sys.path.insert(0,sys.argv[1]);from framebridge_expanded.connection_background import worker_main;worker_main(sys.argv[2],int(sys.argv[3]))"
|
_BOOTSTRAP = "import sys;sys.path.insert(0,sys.argv[1]);from framebridge_expanded.connection_background import worker_main;worker_main(sys.argv[2],int(sys.argv[3]))"
|
||||||
_PACKAGE_PARENT = str(Path(__file__).resolve().parents[1])
|
_PACKAGE_PARENT = str(Path(__file__).resolve().parents[1])
|
||||||
_STATES = {"starting", "checking", "access", "ready", "retrying", "rejected", "unverified", "error", "stopped", "closed"}
|
_STATES = {"starting", "checking", "access", "ready", "retrying", "rejected", "unverified", "error", "stopped", "closed"}
|
||||||
|
_RUNTIME_PARENT = Path("/run/user")
|
||||||
|
_HEARTBEAT_BACKEND = "user-runtime-v1"
|
||||||
|
_IDENTITY_FIELDS = ("pid", "uid", "start_ticks", "boot_id", "session_id", "process_group", "state_dir", "lock_fd")
|
||||||
|
_DURABLE_HEARTBEAT_INTERVAL = 5.0
|
||||||
_MESSAGES = {
|
_MESSAGES = {
|
||||||
"starting": "[1/3] Starting the background tunnel client.",
|
"starting": "[1/3] Starting the background tunnel client.",
|
||||||
"checking": "[2/3] Verifying the local MCP service.",
|
"checking": "[2/3] Verifying the local MCP service.",
|
||||||
@@ -59,6 +64,40 @@ def _checked_fd(path, flags, create=False):
|
|||||||
raise
|
raise
|
||||||
|
|
||||||
|
|
||||||
|
def _heartbeat_directory(state, create=False):
|
||||||
|
"""Keep disposable liveness updates out of the durable profile filesystem.
|
||||||
|
|
||||||
|
Do not create a login runtime directory, follow symlinks, change existing
|
||||||
|
permissions, or trust an arbitrary XDG_RUNTIME_DIR supplied by a caller.
|
||||||
|
Hosts without a user runtime directory retain bounded durable heartbeats.
|
||||||
|
"""
|
||||||
|
root = _RUNTIME_PARENT / str(os.getuid())
|
||||||
|
for parent in (_RUNTIME_PARENT.parent, _RUNTIME_PARENT):
|
||||||
|
try:
|
||||||
|
parent_info = parent.lstat()
|
||||||
|
except FileNotFoundError:
|
||||||
|
return None
|
||||||
|
if not stat.S_ISDIR(parent_info.st_mode) or parent_info.st_uid not in (0, os.getuid()) or stat.S_IMODE(parent_info.st_mode) & 0o022:
|
||||||
|
raise RuntimeError("The user runtime parent directory is unsafe.")
|
||||||
|
try:
|
||||||
|
info = root.lstat()
|
||||||
|
except FileNotFoundError:
|
||||||
|
return None
|
||||||
|
if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) & 0o077:
|
||||||
|
raise RuntimeError("The user runtime directory is not private and owned by this user.")
|
||||||
|
name = "framebridge-connection-" + hashlib.sha256(str(state_path(state)).encode()).hexdigest()
|
||||||
|
directory = root / name
|
||||||
|
if create:
|
||||||
|
return private_dir(directory)
|
||||||
|
try:
|
||||||
|
info = directory.lstat()
|
||||||
|
except FileNotFoundError:
|
||||||
|
return None
|
||||||
|
if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) & 0o077:
|
||||||
|
raise RuntimeError("The connection heartbeat directory is not private and owned by this user.")
|
||||||
|
return directory
|
||||||
|
|
||||||
|
|
||||||
def _read(path):
|
def _read(path):
|
||||||
try:
|
try:
|
||||||
fd = _checked_fd(path, os.O_RDONLY)
|
fd = _checked_fd(path, os.O_RDONLY)
|
||||||
@@ -146,6 +185,11 @@ def status(state):
|
|||||||
if not alive and phase not in {"error", "closed", "stopped"}:
|
if not alive and phase not in {"error", "closed", "stopped"}:
|
||||||
phase = "stopped"
|
phase = "stopped"
|
||||||
checked = record.get("verified_at")
|
checked = record.get("verified_at")
|
||||||
|
if record.get("heartbeat_backend") == _HEARTBEAT_BACKEND:
|
||||||
|
heartbeat_directory = _heartbeat_directory(state)
|
||||||
|
heartbeat = _read(heartbeat_directory / "status.json") if heartbeat_directory else {}
|
||||||
|
same_worker = all(heartbeat.get(key) == record.get(key) for key in _IDENTITY_FIELDS)
|
||||||
|
checked = heartbeat.get("verified_at") if same_worker and heartbeat.get("state") == phase else None
|
||||||
verified = alive and phase == "ready" and type(checked) in (int, float) and 0 <= time.time() - checked <= 15
|
verified = alive and phase == "ready" and type(checked) in (int, float) and 0 <= time.time() - checked <= 15
|
||||||
if alive and phase == "ready" and not verified:
|
if alive and phase == "ready" and not verified:
|
||||||
phase = "retrying"
|
phase = "retrying"
|
||||||
@@ -185,9 +229,14 @@ def disconnect(state, *, timeout=16):
|
|||||||
|
|
||||||
class _StatusOutput:
|
class _StatusOutput:
|
||||||
"""Progress destination owned by the worker, with no parent pipe or terminal."""
|
"""Progress destination owned by the worker, with no parent pipe or terminal."""
|
||||||
def __init__(self, path, identity):
|
def __init__(self, path, identity, heartbeat_path=None):
|
||||||
self.path = path
|
self.path = path
|
||||||
self.record = dict(identity)
|
self.record = dict(identity)
|
||||||
|
self.heartbeat_path = heartbeat_path
|
||||||
|
if heartbeat_path is not None:
|
||||||
|
self.record["heartbeat_backend"] = _HEARTBEAT_BACKEND
|
||||||
|
self.last_observed = None
|
||||||
|
self.last_durable_write = 0.0
|
||||||
self.pending = ""
|
self.pending = ""
|
||||||
self.change("starting", "[1/3] Starting the background tunnel client.")
|
self.change("starting", "[1/3] Starting the background tunnel client.")
|
||||||
|
|
||||||
@@ -198,13 +247,25 @@ class _StatusOutput:
|
|||||||
pass
|
pass
|
||||||
|
|
||||||
def change(self, state, message):
|
def change(self, state, message):
|
||||||
|
if self.record.get("state") == state and self.record.get("message") == message:
|
||||||
|
return
|
||||||
self.record.update(state=state, message=message, updated_at=time.time())
|
self.record.update(state=state, message=message, updated_at=time.time())
|
||||||
_write(self.path, self.record)
|
_write(self.path, self.record)
|
||||||
|
self.last_durable_write = time.monotonic()
|
||||||
|
|
||||||
def observe(self, state):
|
def observe(self, state):
|
||||||
self.record["checked_at"] = time.time()
|
self.record["checked_at"] = time.time()
|
||||||
self.record["verified_at"] = time.time() if state == "ready" else None
|
self.record["verified_at"] = time.time() if state == "ready" else None
|
||||||
_write(self.path, self.record)
|
if self.heartbeat_path is not None:
|
||||||
|
heartbeat = {key: self.record[key] for key in _IDENTITY_FIELDS}
|
||||||
|
heartbeat.update(state=state, checked_at=self.record["checked_at"], verified_at=self.record["verified_at"])
|
||||||
|
_write(self.heartbeat_path, heartbeat)
|
||||||
|
elif state != self.last_observed or time.monotonic() - self.last_durable_write >= _DURABLE_HEARTBEAT_INTERVAL:
|
||||||
|
# Legacy/manual sessions can run without systemd's user runtime
|
||||||
|
# directory. Preserve the 15-second freshness contract there too.
|
||||||
|
_write(self.path, self.record)
|
||||||
|
self.last_durable_write = time.monotonic()
|
||||||
|
self.last_observed = state
|
||||||
|
|
||||||
def write(self, text):
|
def write(self, text):
|
||||||
self.pending += text
|
self.pending += text
|
||||||
@@ -243,7 +304,9 @@ def worker_main(state, lock_fd):
|
|||||||
return
|
return
|
||||||
if not isinstance(command, list) or not command or any(not isinstance(v, str) or "\0" in v for v in command):
|
if not isinstance(command, list) or not command or any(not isinstance(v, str) or "\0" in v for v in command):
|
||||||
return
|
return
|
||||||
sink = _StatusOutput(directory / "status.json", _identity(os.getpid(), state, lock_fd))
|
heartbeat_directory = _heartbeat_directory(state, create=True)
|
||||||
|
heartbeat_path = heartbeat_directory / "status.json" if heartbeat_directory else None
|
||||||
|
sink = _StatusOutput(directory / "status.json", _identity(os.getpid(), state, lock_fd), heartbeat_path)
|
||||||
from .tunnel import run_foreground
|
from .tunnel import run_foreground
|
||||||
rc = run_foreground(command, credential, state=state, output=sink, observe=sink.observe)
|
rc = run_foreground(command, credential, state=state, output=sink, observe=sink.observe)
|
||||||
except BaseException:
|
except BaseException:
|
||||||
|
|||||||
@@ -164,6 +164,19 @@ def resolve_node(alias: str) -> dict[str, Any]:
|
|||||||
return matches[0]
|
return matches[0]
|
||||||
|
|
||||||
|
|
||||||
|
def _target_identity(requested: str, node: dict[str, Any]) -> dict[str, Any]:
|
||||||
|
"""Describe the confirmed route, never identity claimed by a node response."""
|
||||||
|
return {
|
||||||
|
"requested_target": requested,
|
||||||
|
"resolved_target": node["alias"],
|
||||||
|
"node": node["alias"],
|
||||||
|
"target": "LOCAL" if node["transport"] == "local" else node["alias"],
|
||||||
|
"node_id": node["node_id"],
|
||||||
|
"hostname": node.get("hostname"),
|
||||||
|
"transport": node["transport"],
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
def _normalize_read(capability: str, args: dict[str, Any]) -> dict[str, Any]:
|
def _normalize_read(capability: str, args: dict[str, Any]) -> dict[str, Any]:
|
||||||
bootstrap_original()
|
bootstrap_original()
|
||||||
from framebridge_linux_chatgpt.fleet_routing import ReadCapability, normalize_read_args
|
from framebridge_linux_chatgpt.fleet_routing import ReadCapability, normalize_read_args
|
||||||
@@ -185,6 +198,7 @@ def read_local(capability: str, args: dict[str, Any]) -> dict[str, Any]:
|
|||||||
|
|
||||||
|
|
||||||
def node_read(alias: str, capability: str, args: dict[str, Any]) -> dict[str, Any]:
|
def node_read(alias: str, capability: str, args: dict[str, Any]) -> dict[str, Any]:
|
||||||
|
node = None
|
||||||
try:
|
try:
|
||||||
normalized = _normalize_read(capability, args)
|
normalized = _normalize_read(capability, args)
|
||||||
node = resolve_node(alias)
|
node = resolve_node(alias)
|
||||||
@@ -196,10 +210,13 @@ def node_read(alias: str, capability: str, args: dict[str, Any]) -> dict[str, An
|
|||||||
result = broker.request(node["node_id"], capability, normalized, timeout_s=30)
|
result = broker.request(node["node_id"], capability, normalized, timeout_s=30)
|
||||||
_require(type(result) is dict, "NODE_READ_RESPONSE_INVALID")
|
_require(type(result) is dict, "NODE_READ_RESPONSE_INVALID")
|
||||||
response = dict(result)
|
response = dict(result)
|
||||||
response.update(node=node["alias"], hostname=node["hostname"], transport=node["transport"])
|
response.update(_target_identity(alias, node))
|
||||||
return response
|
return response
|
||||||
except Exception as exc:
|
except Exception as exc:
|
||||||
return {"ok": False, "error": str(exc) if isinstance(exc, FleetError) else "NODE_READ_FAILED"}
|
response = {"ok": False, "error": str(exc) if isinstance(exc, FleetError) else "NODE_READ_FAILED"}
|
||||||
|
if node is not None:
|
||||||
|
response.update(_target_identity(alias, node))
|
||||||
|
return response
|
||||||
|
|
||||||
|
|
||||||
def _exec_payload(script: str, authorized: bool, timeout_s: int, job_id: str,
|
def _exec_payload(script: str, authorized: bool, timeout_s: int, job_id: str,
|
||||||
@@ -224,6 +241,7 @@ def _exec_payload(script: str, authorized: bool, timeout_s: int, job_id: str,
|
|||||||
|
|
||||||
def execute_node(alias: str, script: str, authorized: bool, timeout_s: int = 120,
|
def execute_node(alias: str, script: str, authorized: bool, timeout_s: int = 120,
|
||||||
job_id: str = "", sha256: str = "", include_stdout: bool = False) -> dict[str, Any]:
|
job_id: str = "", sha256: str = "", include_stdout: bool = False) -> dict[str, Any]:
|
||||||
|
node = None
|
||||||
try:
|
try:
|
||||||
payload = _exec_payload(script, authorized, timeout_s, job_id, sha256, include_stdout)
|
payload = _exec_payload(script, authorized, timeout_s, job_id, sha256, include_stdout)
|
||||||
node = resolve_node(alias)
|
node = resolve_node(alias)
|
||||||
@@ -241,20 +259,24 @@ def execute_node(alias: str, script: str, authorized: bool, timeout_s: int = 120
|
|||||||
"NODE_EXEC_JOB_BINDING_INVALID")
|
"NODE_EXEC_JOB_BINDING_INVALID")
|
||||||
_require(response.get("mcp_script_sha256", response.get("command_sha256")) == payload["sha256"],
|
_require(response.get("mcp_script_sha256", response.get("command_sha256")) == payload["sha256"],
|
||||||
"NODE_EXEC_HASH_BINDING_INVALID")
|
"NODE_EXEC_HASH_BINDING_INVALID")
|
||||||
response.update(target="LOCAL" if node["transport"] == "local" else node["alias"],
|
response.update(_target_identity(alias, node))
|
||||||
node_id=node["node_id"], mcp_job_id=payload["job_id"],
|
response.update(mcp_job_id=payload["job_id"],
|
||||||
mcp_script_sha256=payload["sha256"])
|
mcp_script_sha256=payload["sha256"])
|
||||||
if include_stdout is not True:
|
if include_stdout is not True:
|
||||||
response.pop("stdout", None)
|
response.pop("stdout", None)
|
||||||
return response
|
return response
|
||||||
except Exception as exc:
|
except Exception as exc:
|
||||||
return {"ok": False, "error": str(exc) if isinstance(exc, FleetError) else "NODE_EXEC_FAILED"}
|
response = {"ok": False, "error": str(exc) if isinstance(exc, FleetError) else "NODE_EXEC_FAILED"}
|
||||||
|
if node is not None:
|
||||||
|
response.update(_target_identity(alias, node))
|
||||||
|
return response
|
||||||
|
|
||||||
|
|
||||||
def execute_screen_node(alias: str, script: str, authorized: bool, timeout_s: int = 30,
|
def execute_screen_node(alias: str, script: str, authorized: bool, timeout_s: int = 30,
|
||||||
job_id: str = "", sha256: str = "", include_stdout: bool = False) -> dict[str, Any]:
|
job_id: str = "", sha256: str = "", include_stdout: bool = False) -> dict[str, Any]:
|
||||||
"""Use the same confirmed-node authority with an explicit non-shell screen operation."""
|
"""Use the same confirmed-node authority with an explicit non-shell screen operation."""
|
||||||
from .real_screen.screen_transport import REQUEST_TYPE, validate_payload, ScreenTransportError
|
from .real_screen.screen_transport import REQUEST_TYPE, validate_payload, ScreenTransportError
|
||||||
|
node = None
|
||||||
try:
|
try:
|
||||||
_require(type(timeout_s) is int and 1 <= timeout_s <= 30, "INVALID_SCREEN_TIMEOUT")
|
_require(type(timeout_s) is int and 1 <= timeout_s <= 30, "INVALID_SCREEN_TIMEOUT")
|
||||||
payload = _exec_payload(script, authorized, timeout_s, job_id, sha256, include_stdout)
|
payload = _exec_payload(script, authorized, timeout_s, job_id, sha256, include_stdout)
|
||||||
@@ -280,16 +302,20 @@ def execute_screen_node(alias: str, script: str, authorized: bool, timeout_s: in
|
|||||||
from .real_screen.screen_rpc import encode
|
from .real_screen.screen_rpc import encode
|
||||||
response.update(ok=False, exit_code="1", stdout_truncated=False,
|
response.update(ok=False, exit_code="1", stdout_truncated=False,
|
||||||
stdout=encode({"ok": False, "error": {"code": "SCREEN_RPC_UNSUPPORTED_ON_NODE"}}).decode("ascii") + "\n")
|
stdout=encode({"ok": False, "error": {"code": "SCREEN_RPC_UNSUPPORTED_ON_NODE"}}).decode("ascii") + "\n")
|
||||||
response.update(target="LOCAL" if node["transport"] == "local" else node["alias"],
|
response.update(_target_identity(alias, node))
|
||||||
node_id=node["node_id"], mcp_job_id=payload["job_id"],
|
response.update(mcp_job_id=payload["job_id"],
|
||||||
mcp_script_sha256=payload["sha256"])
|
mcp_script_sha256=payload["sha256"])
|
||||||
return response
|
return response
|
||||||
except Exception as exc:
|
except Exception as exc:
|
||||||
return {"ok": False, "error": str(exc) if isinstance(exc, (FleetError, ScreenTransportError)) else "SCREEN_RPC_FAILED"}
|
response = {"ok": False, "error": str(exc) if isinstance(exc, (FleetError, ScreenTransportError)) else "SCREEN_RPC_FAILED"}
|
||||||
|
if node is not None:
|
||||||
|
response.update(_target_identity(alias, node))
|
||||||
|
return response
|
||||||
|
|
||||||
|
|
||||||
def cua_node(alias: str, payload: dict[str, Any], authorized: bool,
|
def cua_node(alias: str, payload: dict[str, Any], authorized: bool,
|
||||||
timeout_s: int = 60, job_id: str = "") -> dict[str, Any]:
|
timeout_s: int = 60, job_id: str = "") -> dict[str, Any]:
|
||||||
|
node = None
|
||||||
try:
|
try:
|
||||||
_require(authorized is True, "AUTHORIZED_TRUE_REQUIRED")
|
_require(authorized is True, "AUTHORIZED_TRUE_REQUIRED")
|
||||||
_require(type(payload) is dict, "CUA_PAYLOAD_REQUIRED")
|
_require(type(payload) is dict, "CUA_PAYLOAD_REQUIRED")
|
||||||
@@ -316,10 +342,13 @@ def cua_node(alias: str, payload: dict[str, Any], authorized: bool,
|
|||||||
response = dict(result)
|
response = dict(result)
|
||||||
if response.get("ok") is True:
|
if response.get("ok") is True:
|
||||||
_require(response.get("job_id") == job, "NODE_CUA_JOB_BINDING_INVALID")
|
_require(response.get("job_id") == job, "NODE_CUA_JOB_BINDING_INVALID")
|
||||||
response.update(target="LOCAL" if node["transport"] == "local" else node["alias"], node_id=node["node_id"])
|
response.update(_target_identity(alias, node))
|
||||||
return response
|
return response
|
||||||
except Exception as exc:
|
except Exception as exc:
|
||||||
return {"ok": False, "error": str(exc) if isinstance(exc, FleetError) else "NODE_CUA_FAILED"}
|
response = {"ok": False, "error": str(exc) if isinstance(exc, FleetError) else "NODE_CUA_FAILED"}
|
||||||
|
if node is not None:
|
||||||
|
response.update(_target_identity(alias, node))
|
||||||
|
return response
|
||||||
|
|
||||||
|
|
||||||
def main() -> None:
|
def main() -> None:
|
||||||
|
|||||||
@@ -8,7 +8,7 @@ GUIDE = {'start': {'title': 'Start with FrameBridge',
|
|||||||
'commands': ['fb help', 'fb status', 'fb --json status']},
|
'commands': ['fb help', 'fb status', 'fb --json status']},
|
||||||
{'heading': 'Install and connect',
|
{'heading': 'Install and connect',
|
||||||
'body': 'Install the package built for your exact Debian 13, Ubuntu 24.04 or Linux Mint 22.x amd64 profile. These are the three release profiles; other distributions and architectures are outside this release. Keep the distribution system Python: 3.13 on Debian 13, 3.12 on Ubuntu 24.04 and Mint 22.x. Use the matching signed APT suite: trixie, noble or mint22. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.',
|
'body': 'Install the package built for your exact Debian 13, Ubuntu 24.04 or Linux Mint 22.x amd64 profile. These are the three release profiles; other distributions and architectures are outside this release. Keep the distribution system Python: 3.13 on Debian 13, 3.12 on Ubuntu 24.04 and Mint 22.x. Use the matching signed APT suite: trixie, noble or mint22. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal; advanced setup is optional for central/node roles and public settings.',
|
||||||
'commands': ["sudo apt install ./framebridge-expanded_" + __version__ + "_amd64.deb", 'fb connect']},
|
'commands': ['fb connect']},
|
||||||
{'heading': 'Updating and removal',
|
{'heading': 'Updating and removal',
|
||||||
'body': 'Install an official update through the normal package manager when that update has been published. Normal removal stops package-owned managed processes and can retain the user profile and encrypted connection material; it is not a credential-forgetting operation. On systemd 255, package removal also revokes the administrative boot-credential grant. After reinstalling, run fb connect interactively to provision that grant again; retained files alone do not restore startup. Use the explicit credentials forget action first when that is your intended outcome. Do not assume purge erases user-profile data. An explicit downgrade also revokes administrative helper grants before the older package files replace the helper. Helper-backed profiles require a new interactive connect with a compatible package before managed startup can be restored.',
|
'body': 'Install an official update through the normal package manager when that update has been published. Normal removal stops package-owned managed processes and can retain the user profile and encrypted connection material; it is not a credential-forgetting operation. On systemd 255, package removal also revokes the administrative boot-credential grant. After reinstalling, run fb connect interactively to provision that grant again; retained files alone do not restore startup. Use the explicit credentials forget action first when that is your intended outcome. Do not assume purge erases user-profile data. An explicit downgrade also revokes administrative helper grants before the older package files replace the helper. Helper-backed profiles require a new interactive connect with a compatible package before managed startup can be restored.',
|
||||||
'commands': ['sudo dpkg --remove framebridge-original-expanded']},
|
'commands': ['sudo dpkg --remove framebridge-original-expanded']},
|
||||||
@@ -50,6 +50,7 @@ GUIDE = {'start': {'title': 'Start with FrameBridge',
|
|||||||
'fb status boot',
|
'fb status boot',
|
||||||
'fb status console',
|
'fb status console',
|
||||||
'fb doctor',
|
'fb doctor',
|
||||||
|
'fb health',
|
||||||
'fb setup',
|
'fb setup',
|
||||||
'fb console',
|
'fb console',
|
||||||
'fb help']},
|
'fb help']},
|
||||||
@@ -210,7 +211,11 @@ GUIDE = {'start': {'title': 'Start with FrameBridge',
|
|||||||
{'heading': 'Targets',
|
{'heading': 'Targets',
|
||||||
'body': 'LOCAL means the actual receiving machine. Use enrolled, '
|
'body': 'LOCAL means the actual receiving machine. Use enrolled, '
|
||||||
'confirmed aliases or IDs and inspect the selected target before '
|
'confirmed aliases or IDs and inspect the selected target before '
|
||||||
'work. Do not guess SSH identities or use historical lab '
|
'work. Fleet results include requested_target, resolved_target, '
|
||||||
|
'node_id, hostname and transport from the confirmed descriptor. '
|
||||||
|
'The compatibility target field can remain LOCAL; resolved_target '
|
||||||
|
'names the actual local computer. Unknown targets never fall back '
|
||||||
|
'to LOCAL. Do not guess SSH identities or use historical lab '
|
||||||
'hostnames as defaults. CLI tty --node can use the authenticated '
|
'hostnames as defaults. CLI tty --node can use the authenticated '
|
||||||
'node transport. The interactive console command is local; run it '
|
'node transport. The interactive console command is local; run it '
|
||||||
'at the destination or use an explicitly configured SSH '
|
'at the destination or use an explicitly configured SSH '
|
||||||
@@ -327,8 +332,11 @@ GUIDE = {'start': {'title': 'Start with FrameBridge',
|
|||||||
'fb status runtime',
|
'fb status runtime',
|
||||||
'fb status boot']},
|
'fb status boot']},
|
||||||
{'heading': 'Doctor',
|
{'heading': 'Doctor',
|
||||||
'body': 'doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes. Candidate eligibility checks the exact OS release, amd64 architecture, package profile and CPython ABI before starting native components. Debian 13/LMDE 7 use cp313, Ubuntu 24.04/Mint 22.x use cp312, and Ubuntu 26.04 uses cp314. A matching profile does not establish a tested installation; never repair an ABI mismatch by replacing system Python or weakening package dependencies.',
|
'body': 'doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes. Eligibility checks the exact OS release, amd64 architecture, package profile and CPython ABI before starting native components. The published 0.3.3 scope is Debian 13 with cp313 and Ubuntu 24.04/Mint 22.x with cp312. LMDE 7 and Ubuntu 26.04 builder experiments remain outside that validated scope. A matching profile or a successful development build does not establish a tested installation; never repair an ABI mismatch by replacing system Python or weakening package dependencies.',
|
||||||
'commands': ['fb doctor']},
|
'commands': ['fb doctor']},
|
||||||
|
{'heading': 'Local health summary',
|
||||||
|
'body': 'health combines this local profile\'s existing status and prerequisite observations into an allowlisted report. It identifies LOCAL as this computer and reports the profile, role, connection intent, local tools, boot policy and desktop availability. It never starts, repairs, connects, changes boot policy or creates an absent profile. It does not scan the fleet or probe terminal commands, screen capture or input. States are healthy, paused, degraded, unavailable and unconfigured. An intentional connection pause can be healthy; missing information cannot. JSON result.ok describes observation completeness; result.health.healthy describes health. Health exits 0 for a complete healthy or intentionally paused observation and 1 for degraded, unavailable or unconfigured state. The CLI version is not proof of the running version. Detailed troubleshooting remains local in status and doctor.',
|
||||||
|
'commands': ['fb health', 'fb --json health']},
|
||||||
{'heading': 'Logs and progress',
|
{'heading': 'Logs and progress',
|
||||||
'body': 'Normal connection presents concise progress and a final '
|
'body': 'Normal connection presents concise progress and a final '
|
||||||
'result, then returns to the prompt. Detailed diagnostics '
|
'result, then returns to the prompt. Detailed diagnostics '
|
||||||
|
|||||||
@@ -0,0 +1,234 @@
|
|||||||
|
"""Read-only, allowlisted health observations for one local FrameBridge profile.
|
||||||
|
|
||||||
|
This combines existing status and prerequisite checks. It does not execute a
|
||||||
|
terminal/CUA probe, contact another node, repair a profile or change boot intent.
|
||||||
|
Snapshot success, observed readiness and compatibility are separate facts.
|
||||||
|
"""
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from datetime import datetime, timezone
|
||||||
|
import re
|
||||||
|
import socket
|
||||||
|
import uuid
|
||||||
|
|
||||||
|
from . import __version__, lifecycle, runtime
|
||||||
|
from .config import state_path
|
||||||
|
|
||||||
|
|
||||||
|
_KINDS = frozenset({"physical-x11", "virtual-x11", "text", "not_started", "unavailable"})
|
||||||
|
_PHASES = frozenset({"starting", "checking", "access", "unverified", "ready",
|
||||||
|
"retrying", "error", "rejected", "stopped", "closed"})
|
||||||
|
_SERVICES = frozenset({"active", "activating", "deactivating", "inactive", "failed",
|
||||||
|
"reloading", "maintenance", "refreshing", "not_configured"})
|
||||||
|
_CAPABILITIES = ("fbexec", "fbterm", "cua_tty_module", "graphical_cua")
|
||||||
|
|
||||||
|
|
||||||
|
def _mapping(value):
|
||||||
|
return value if isinstance(value, dict) else {}
|
||||||
|
|
||||||
|
|
||||||
|
def _boolean(value):
|
||||||
|
return value if type(value) is bool else None
|
||||||
|
|
||||||
|
|
||||||
|
def _name(value):
|
||||||
|
return value if isinstance(value, str) and re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,252}", value) else None
|
||||||
|
|
||||||
|
|
||||||
|
def _node_id(value):
|
||||||
|
try:
|
||||||
|
return str(uuid.UUID(value)) if isinstance(value, str) else None
|
||||||
|
except (ValueError, AttributeError):
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def _count(value):
|
||||||
|
return len(value) if isinstance(value, list) else 0
|
||||||
|
|
||||||
|
|
||||||
|
def _choice(value, options, fallback="unavailable"):
|
||||||
|
return value if isinstance(value, str) and value in options else fallback
|
||||||
|
|
||||||
|
|
||||||
|
def _runtime_state(value):
|
||||||
|
if value.get("ok") is False or value.get("status_unavailable") or type(value.get("running")) is not bool:
|
||||||
|
return "unavailable"
|
||||||
|
if value.get("ready") is True and value.get("running") is True:
|
||||||
|
return "ready"
|
||||||
|
return "running" if value["running"] else "stopped"
|
||||||
|
|
||||||
|
|
||||||
|
def _boot_state(value):
|
||||||
|
if value.get("configured") is False:
|
||||||
|
return "not_configured"
|
||||||
|
if value.get("configured") is not True or type(value.get("enabled")) is not bool:
|
||||||
|
return "unavailable"
|
||||||
|
return "enabled" if value["enabled"] else "disabled"
|
||||||
|
|
||||||
|
|
||||||
|
def build_report(status_snapshot=None, doctor_snapshot=None, *, observed_at=None,
|
||||||
|
host=None, status_available=True, doctor_available=True):
|
||||||
|
"""Project snapshots onto a fixed public schema; never copy raw dictionaries.
|
||||||
|
|
||||||
|
Errors deliberately omit exception text and diagnostic free text. Existing
|
||||||
|
local ``fb doctor`` remains the detailed troubleshooting interface; this
|
||||||
|
summary can be shown to an assistant without connection metadata or paths.
|
||||||
|
"""
|
||||||
|
status = _mapping(status_snapshot)
|
||||||
|
diagnosis = _mapping(doctor_snapshot)
|
||||||
|
local = _mapping(status.get("runtime"))
|
||||||
|
connection = _mapping(status.get("connection"))
|
||||||
|
boot = _mapping(status.get("boot"))
|
||||||
|
platform = _mapping(diagnosis.get("platform_compatibility"))
|
||||||
|
capabilities = _mapping(local.get("capabilities"))
|
||||||
|
prerequisite_capabilities = _mapping(diagnosis.get("capabilities"))
|
||||||
|
context = _mapping(local.get("display_context"))
|
||||||
|
status_available = bool(status_available and isinstance(status_snapshot, dict) and status.get("ok") is not False)
|
||||||
|
configured = _boolean(status.get("configured")) if status_available else None
|
||||||
|
role = status.get("role") or local.get("role")
|
||||||
|
role = _choice(role, {"standalone", "central", "node"}, None)
|
||||||
|
local_state = _runtime_state(local) if configured is not False else "not_configured"
|
||||||
|
phase = _choice(connection.get("state"), _PHASES)
|
||||||
|
intent = _choice(status.get("desired_connection"), {"connected", "disconnected", "not_configured", "not_applicable"})
|
||||||
|
kind = _choice(context.get("kind"), _KINDS)
|
||||||
|
doctor_available = bool(doctor_available and isinstance(doctor_snapshot, dict) and type(diagnosis.get("ok")) is bool) if configured else False
|
||||||
|
diagnostics_ok = _boolean(diagnosis.get("ok")) if doctor_available else None
|
||||||
|
connection_available = role == "node" or (
|
||||||
|
bool(connection) and connection.get("ok") is not False
|
||||||
|
and phase != "unavailable" and type(connection.get("verified")) is bool)
|
||||||
|
boot_available = _boot_state(boot) != "unavailable"
|
||||||
|
issues = []
|
||||||
|
if not status_available:
|
||||||
|
issues.append("STATUS_UNAVAILABLE")
|
||||||
|
if configured and not doctor_available:
|
||||||
|
issues.append("DIAGNOSTICS_UNAVAILABLE")
|
||||||
|
if configured and local_state == "unavailable":
|
||||||
|
issues.append("RUNTIME_STATUS_UNAVAILABLE")
|
||||||
|
if configured and not connection_available:
|
||||||
|
issues.append("CONNECTION_STATUS_UNAVAILABLE")
|
||||||
|
if configured and not boot_available:
|
||||||
|
issues.append("BOOT_STATUS_UNAVAILABLE")
|
||||||
|
if diagnostics_ok is False:
|
||||||
|
issues.append("PREREQUISITES_NEED_ATTENTION")
|
||||||
|
if configured is False:
|
||||||
|
health_state, healthy = "unconfigured", False
|
||||||
|
elif (not status_available or configured is None or role is None or not doctor_available
|
||||||
|
or local_state == "unavailable" or not connection_available or not boot_available):
|
||||||
|
health_state, healthy = "unavailable", None
|
||||||
|
elif diagnostics_ok is not True or local_state != "ready":
|
||||||
|
health_state, healthy = "degraded", False
|
||||||
|
elif role == "node":
|
||||||
|
health_state, healthy = "healthy", True
|
||||||
|
elif intent == "disconnected":
|
||||||
|
if connection.get("verified") is False and connection.get("alive") is not True and phase in {"stopped", "closed"}:
|
||||||
|
health_state, healthy = "paused", True
|
||||||
|
else:
|
||||||
|
health_state, healthy = "degraded", False
|
||||||
|
issues.append("CONNECTION_INTENT_MISMATCH")
|
||||||
|
elif connection.get("verified") is True:
|
||||||
|
health_state, healthy = "healthy", True
|
||||||
|
else:
|
||||||
|
health_state, healthy = "degraded", False
|
||||||
|
issues.append("CONNECTION_NOT_VERIFIED")
|
||||||
|
if configured and local_state in {"running", "stopped"}:
|
||||||
|
issues.append("LOCAL_TOOLS_NOT_READY")
|
||||||
|
observation_ok = (status_available and configured is not None and local_state != "unavailable"
|
||||||
|
and (configured is False or (doctor_available and connection_available
|
||||||
|
and boot_available and role is not None)))
|
||||||
|
build_profile = platform.get("artifact_profile_id") or platform.get("profile_id")
|
||||||
|
missing = diagnosis.get("missing_commands")
|
||||||
|
missing = sorted({v for v in missing if isinstance(v, str) and re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.+-]{0,63}", v)}) if isinstance(missing, list) else []
|
||||||
|
notes = ["This is a local profile observation, not a fleet scan.",
|
||||||
|
"Status and prerequisites are sampled sequentially; this is not an atomic snapshot.",
|
||||||
|
"No FBEXEC/FBTERM command, screen capture or input probe was performed."]
|
||||||
|
if role == "node":
|
||||||
|
notes.append("The central computer provides the ChatGPT connection; this report does not verify that central connection.")
|
||||||
|
if configured is False:
|
||||||
|
notes.append("This profile is not configured. No profile or connection was created.")
|
||||||
|
if kind == "text":
|
||||||
|
notes.append("Text mode does not require a graphical session.")
|
||||||
|
return {
|
||||||
|
"schema_version": 1, "ok": observation_ok, "read_only": True,
|
||||||
|
"observed_at": observed_at or datetime.now(timezone.utc).isoformat(),
|
||||||
|
"effective_target": {"selector": "LOCAL", "host": _name(host),
|
||||||
|
"profile_name": _name(status.get("name") or local.get("name")),
|
||||||
|
"role": role, "node_id": _node_id(local.get("node_id"))},
|
||||||
|
"software": {"cli_version": __version__, "runtime_version": None,
|
||||||
|
"runtime_version_status": "not_reported"},
|
||||||
|
"health": {"state": health_state, "healthy": healthy, "issues": issues},
|
||||||
|
"runtime": {"state": local_state, "running": _boolean(local.get("running")) if configured else None,
|
||||||
|
"ready": _boolean(local.get("ready")) if configured else None,
|
||||||
|
"availability": {k: _boolean(capabilities.get(k)) for k in _CAPABILITIES},
|
||||||
|
"operational_probe_performed": False},
|
||||||
|
"connection": {"state": "managed_by_central" if role == "node" else phase,
|
||||||
|
"verified": None if role == "node" else _boolean(connection.get("verified")),
|
||||||
|
"desired": intent},
|
||||||
|
"boot": {"policy": _boot_state(boot),
|
||||||
|
"service_state": _choice(boot.get("service_state"), _SERVICES)},
|
||||||
|
"prerequisites": {"state": "not_run" if configured is False else ("passed" if diagnostics_ok is True else "needs_attention" if diagnostics_ok is False else "unavailable"),
|
||||||
|
"compatible": _boolean(platform.get("ok")) if doctor_available else None,
|
||||||
|
"profile_id": _name(build_profile),
|
||||||
|
"validation_status": _choice(platform.get("validation_status"), {"candidate", "release_build", "validated", "source-unvalidated"}, "not_reported"),
|
||||||
|
"missing_commands": missing,
|
||||||
|
"issue_count": _count(diagnosis.get("issues")),
|
||||||
|
"compatibility_issue_count": _count(platform.get("issues")),
|
||||||
|
"availability": {k: _boolean(prerequisite_capabilities.get(k)) for k in _CAPABILITIES}},
|
||||||
|
"desktop": {"kind": kind, "graphical_available": _boolean(capabilities.get("graphical_cua")),
|
||||||
|
"capture_verified_by_this_report": False, "input_verified_by_this_report": False},
|
||||||
|
"notes": notes,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def collect(state):
|
||||||
|
"""Observe only the selected local profile without creating or repairing it."""
|
||||||
|
state = state_path(state)
|
||||||
|
status_snapshot, diagnosis = None, None
|
||||||
|
status_available = doctor_available = True
|
||||||
|
try:
|
||||||
|
status_snapshot = lifecycle.status(state)
|
||||||
|
except Exception:
|
||||||
|
status_available = False
|
||||||
|
if _mapping(status_snapshot).get("configured") is True:
|
||||||
|
try:
|
||||||
|
diagnosis = runtime.doctor(state)
|
||||||
|
except Exception:
|
||||||
|
doctor_available = False
|
||||||
|
else:
|
||||||
|
doctor_available = False
|
||||||
|
try:
|
||||||
|
host = socket.gethostname()
|
||||||
|
except OSError:
|
||||||
|
host = None
|
||||||
|
return build_report(status_snapshot, diagnosis, host=host,
|
||||||
|
status_available=status_available, doctor_available=doctor_available)
|
||||||
|
|
||||||
|
|
||||||
|
def render(report):
|
||||||
|
"""Render the same allowlisted report for a human terminal."""
|
||||||
|
target = report["effective_target"]
|
||||||
|
software = report["software"]
|
||||||
|
state = report["health"]["state"]
|
||||||
|
lines = ["FrameBridge " + software["cli_version"] + " — health: " + state,
|
||||||
|
"Target: LOCAL = this computer (" + (target["host"] or "hostname unavailable") + ")",
|
||||||
|
"Profile: " + (target["profile_name"] or "not available") + " | role: " + (target["role"] or "not available")]
|
||||||
|
if target["node_id"]:
|
||||||
|
lines.append("Node ID: " + target["node_id"])
|
||||||
|
lines.extend(["Observed: " + report["observed_at"],
|
||||||
|
"Local tools: " + report["runtime"]["state"],
|
||||||
|
"Connection: " + ("connected (verified)" if report["connection"]["verified"] is True else report["connection"]["state"]),
|
||||||
|
"Connection intent: " + report["connection"]["desired"],
|
||||||
|
"Automatic startup: " + report["boot"]["policy"],
|
||||||
|
"Current service: " + report["boot"]["service_state"],
|
||||||
|
"Prerequisites: " + report["prerequisites"]["state"]])
|
||||||
|
if report["prerequisites"]["profile_id"]:
|
||||||
|
lines.append("Build profile: " + report["prerequisites"]["profile_id"])
|
||||||
|
lines.append("Desktop: " + report["desktop"]["kind"] + " (capture/input not tested)")
|
||||||
|
for issue in report["health"]["issues"]:
|
||||||
|
lines.append("Finding: " + issue)
|
||||||
|
if report["prerequisites"]["missing_commands"]:
|
||||||
|
lines.append("Missing commands: " + ", ".join(report["prerequisites"]["missing_commands"]))
|
||||||
|
if state in {"degraded", "unavailable"}:
|
||||||
|
lines.append("Inspect details locally: fb status; fb doctor")
|
||||||
|
lines.append("Runtime version: not reported; the CLI version is not proof of the running version.")
|
||||||
|
lines.extend(report["notes"])
|
||||||
|
return "\n".join(lines)
|
||||||
@@ -6,11 +6,13 @@ import gzip
|
|||||||
import hashlib
|
import hashlib
|
||||||
import io
|
import io
|
||||||
import json
|
import json
|
||||||
|
import re
|
||||||
from pathlib import Path
|
from pathlib import Path
|
||||||
import tarfile
|
import tarfile
|
||||||
import sys
|
import sys
|
||||||
|
|
||||||
from build_profiles import CANDIDATE_VERSION, SOURCE_VENDOR, target_profile, validate_vendor, vendor_versions
|
from build_profiles import CANDIDATE_VERSION, SOURCE_VENDOR, target_profile, validate_vendor, vendor_versions
|
||||||
|
from release_metadata import PUBLIC_RELEASE_PROFILES
|
||||||
|
|
||||||
BASE = Path(__file__).resolve().parents[1]
|
BASE = Path(__file__).resolve().parents[1]
|
||||||
ROOT = BASE.parent
|
ROOT = BASE.parent
|
||||||
@@ -25,6 +27,45 @@ BLOG_POLICY_FILES = ("README.md", "LICENSING.md", "POST-TEMPLATE.md", "LICENSE-C
|
|||||||
ARCHIVE_README_NAME = "README-SOURCE-ARCHIVE.md"
|
ARCHIVE_README_NAME = "README-SOURCE-ARCHIVE.md"
|
||||||
DEPENDENCY_SOURCE_ASSETS = [{'filename': 'FrameBridge-0.3.1-Community-Preview1-dependency-sources.tar.gz', 'bytes': 82606998, 'sha256': '64540a85bd65eac3f394d8c0a967cacbc00e112676d57d644dcd1bb691c1926a'}, {'filename': 'FrameBridge-0.3.1-tunnel-client-dependency-sources.tar.gz', 'bytes': 26941745, 'sha256': '6445d4f0e773aba833fe5c610fbae54102b92de2ce636438f769f21e890c2bd9'}]
|
DEPENDENCY_SOURCE_ASSETS = [{'filename': 'FrameBridge-0.3.1-Community-Preview1-dependency-sources.tar.gz', 'bytes': 82606998, 'sha256': '64540a85bd65eac3f394d8c0a967cacbc00e112676d57d644dcd1bb691c1926a'}, {'filename': 'FrameBridge-0.3.1-tunnel-client-dependency-sources.tar.gz', 'bytes': 26941745, 'sha256': '6445d4f0e773aba833fe5c610fbae54102b92de2ce636438f769f21e890c2bd9'}]
|
||||||
ARCHIVE_README = f"# FrameBridge {CANDIDATE_VERSION} compatibility candidate source\n\nThis source archive is a QA candidate, not a signed public release or evidence\nthat an OS/desktop lifecycle has been tested. Original signed 0.3.1 assets retain\ntheir separate immutable identity. Check TARGET-VENDOR-PROVENANCE.json for the\nnative ABI inputs actually included in this archive.\n\nThe offline builder requires Python 3, Debian dpkg/dpkg-deb and documented host\nbuild prerequisites. It writes source/build/<profile> and source/release/<profile>;\nit never installs a package, fetches dependencies, changes system Python or starts\nFrameBridge services. Run from this archive's top-level directory:\n\n python3 source/packaging/build_expanded.py --target debian13-amd64-py313\n python3 source/packaging/build_expanded.py --target lmde7-amd64-py313\n\nIf the cp312 input is recorded as included:\n\n python3 source/packaging/build_expanded.py --target ubuntu24.04-amd64-py312 --vendor-dir source/target-vendors/cp312\n python3 source/packaging/build_expanded.py --target mint22-amd64-py312 --vendor-dir source/target-vendors/cp312\n\nIf the cp314 input is recorded as included:\n\n python3 source/packaging/build_expanded.py --target ubuntu26.04-amd64-py314 --vendor-dir source/target-vendors/cp314\n\nThe default archive includes only the reviewed original cp313 vendor tree.\nThe archive producer can include reviewed alternate ABI trees using:\n\n python3 source/packaging/archive_sources.py --vendor-cp312 /reviewed/vendor-cp312 --vendor-cp314 /reviewed/vendor-cp314\n\nThose arguments must identify complete reviewed trees with the same 29 pinned\ndistribution names/versions as the original. The producer validates WHEEL/RECORD,\nCPython ABI, amd64 ELF and glibc baseline before including them. Local preparation\nmarkers and executable entry-point scripts are omitted. All included files and\ntheir hashes appear in SOURCE-ARCHIVE-MANIFEST.json alongside the finished archive;\nthe embedded provenance records input ABI identity without workstation paths.\n--check-vendor on build_expanded.py validates inputs without building a package.\nAn absent alternate tree must be supplied separately with equivalent provenance;\nchanging Depends cannot convert the original cp313 extensions into cp312/cp314.\n\nPackage output names contain the candidate version and a separate profile\nfolder. release-profile.json inside the installed prefix declares the exact\ncandidate profile. Build success and profile eligibility do not establish a\nvalidated installation, graphical control, real TTY or reboot lifecycle.\n\nOriginal FrameBridge material is GNU GPL version 3 only. Read LICENSE,\nLICENSING.md, COPYRIGHT.md, LICENSE-STATUS.md and OFFICIAL-RELEASES.md for scope,\nattribution, third-party terms and the official-release trust model.\n\nThe project source asset is accompanied by these separate unchanged dependency\nsource assets; they are not embedded or renamed by this helper:\n\n- FrameBridge-0.3.1-Community-Preview1-dependency-sources.tar.gz\n 82,606,998 bytes\n SHA-256 64540a85bd65eac3f394d8c0a967cacbc00e112676d57d644dcd1bb691c1926a\n- FrameBridge-0.3.1-tunnel-client-dependency-sources.tar.gz\n 26,941,745 bytes\n SHA-256 6445d4f0e773aba833fe5c610fbae54102b92de2ce636438f769f21e890c2bd9\n\nThe Preview1 name preserves an immutable shared asset's identity. Retain the R2\nsource-notice supplements and both dependency indices under licensing/third-party.\nMatching package versions do not constitute an independent source rebuild of the\nretained tunnel executable; its exact own-source revision is not asserted.\n\nThe blog directory contains licensing policies and the post template. Draft\narticles, private runtime profiles, QA logs, build outputs and Git history are\noutside the source allowlist. Only source/evidence/BASELINE.json is included from\ntechnical evidence. Release signatures and publication status are separate\nrecords; this candidate archiver does not sign or publish anything.\n".encode("utf-8")
|
ARCHIVE_README = f"# FrameBridge {CANDIDATE_VERSION} compatibility candidate source\n\nThis source archive is a QA candidate, not a signed public release or evidence\nthat an OS/desktop lifecycle has been tested. Original signed 0.3.1 assets retain\ntheir separate immutable identity. Check TARGET-VENDOR-PROVENANCE.json for the\nnative ABI inputs actually included in this archive.\n\nThe offline builder requires Python 3, Debian dpkg/dpkg-deb and documented host\nbuild prerequisites. It writes source/build/<profile> and source/release/<profile>;\nit never installs a package, fetches dependencies, changes system Python or starts\nFrameBridge services. Run from this archive's top-level directory:\n\n python3 source/packaging/build_expanded.py --target debian13-amd64-py313\n python3 source/packaging/build_expanded.py --target lmde7-amd64-py313\n\nIf the cp312 input is recorded as included:\n\n python3 source/packaging/build_expanded.py --target ubuntu24.04-amd64-py312 --vendor-dir source/target-vendors/cp312\n python3 source/packaging/build_expanded.py --target mint22-amd64-py312 --vendor-dir source/target-vendors/cp312\n\nIf the cp314 input is recorded as included:\n\n python3 source/packaging/build_expanded.py --target ubuntu26.04-amd64-py314 --vendor-dir source/target-vendors/cp314\n\nThe default archive includes only the reviewed original cp313 vendor tree.\nThe archive producer can include reviewed alternate ABI trees using:\n\n python3 source/packaging/archive_sources.py --vendor-cp312 /reviewed/vendor-cp312 --vendor-cp314 /reviewed/vendor-cp314\n\nThose arguments must identify complete reviewed trees with the same 29 pinned\ndistribution names/versions as the original. The producer validates WHEEL/RECORD,\nCPython ABI, amd64 ELF and glibc baseline before including them. Local preparation\nmarkers and executable entry-point scripts are omitted. All included files and\ntheir hashes appear in SOURCE-ARCHIVE-MANIFEST.json alongside the finished archive;\nthe embedded provenance records input ABI identity without workstation paths.\n--check-vendor on build_expanded.py validates inputs without building a package.\nAn absent alternate tree must be supplied separately with equivalent provenance;\nchanging Depends cannot convert the original cp313 extensions into cp312/cp314.\n\nPackage output names contain the candidate version and a separate profile\nfolder. release-profile.json inside the installed prefix declares the exact\ncandidate profile. Build success and profile eligibility do not establish a\nvalidated installation, graphical control, real TTY or reboot lifecycle.\n\nOriginal FrameBridge material is GNU GPL version 3 only. Read LICENSE,\nLICENSING.md, COPYRIGHT.md, LICENSE-STATUS.md and OFFICIAL-RELEASES.md for scope,\nattribution, third-party terms and the official-release trust model.\n\nThe project source asset is accompanied by these separate unchanged dependency\nsource assets; they are not embedded or renamed by this helper:\n\n- FrameBridge-0.3.1-Community-Preview1-dependency-sources.tar.gz\n 82,606,998 bytes\n SHA-256 64540a85bd65eac3f394d8c0a967cacbc00e112676d57d644dcd1bb691c1926a\n- FrameBridge-0.3.1-tunnel-client-dependency-sources.tar.gz\n 26,941,745 bytes\n SHA-256 6445d4f0e773aba833fe5c610fbae54102b92de2ce636438f769f21e890c2bd9\n\nThe Preview1 name preserves an immutable shared asset's identity. Retain the R2\nsource-notice supplements and both dependency indices under licensing/third-party.\nMatching package versions do not constitute an independent source rebuild of the\nretained tunnel executable; its exact own-source revision is not asserted.\n\nThe blog directory contains licensing policies and the post template. Draft\narticles, private runtime profiles, QA logs, build outputs and Git history are\noutside the source allowlist. Only source/evidence/BASELINE.json is included from\ntechnical evidence. Release signatures and publication status are separate\nrecords; this candidate archiver does not sign or publish anything.\n".encode("utf-8")
|
||||||
|
PUBLIC_ARCHIVE_README = f"""# FrameBridge {CANDIDATE_VERSION} corresponding source
|
||||||
|
|
||||||
|
This archive supplies the project source and the reviewed cp313 and cp312 vendor
|
||||||
|
inputs for Debian 13, Ubuntu 24.04 and Linux Mint 22.x on amd64. Keep its matching
|
||||||
|
SOURCE-ARCHIVE-MANIFEST.json sidecar beside the archive. Signatures, publication
|
||||||
|
and actual OS lifecycle acceptance are recorded separately; assembly alone does
|
||||||
|
not certify them. Historical signed assets retain their immutable identities.
|
||||||
|
|
||||||
|
The offline builder needs Python 3, dpkg/dpkg-deb and the documented host build
|
||||||
|
prerequisites. It never fetches dependencies, installs packages or starts services.
|
||||||
|
Extract the archive beside its matching sidecar and run from the extracted root:
|
||||||
|
|
||||||
|
python3 source/packaging/build_expanded.py --target debian13-amd64-py313 --public-release --source-manifest ../SOURCE-ARCHIVE-MANIFEST.json
|
||||||
|
python3 source/packaging/build_expanded.py --target ubuntu24.04-amd64-py312 --vendor-dir source/target-vendors/cp312 --public-release --source-manifest ../SOURCE-ARCHIVE-MANIFEST.json
|
||||||
|
python3 source/packaging/build_expanded.py --target mint22-amd64-py312 --vendor-dir source/target-vendors/cp312 --public-release --source-manifest ../SOURCE-ARCHIVE-MANIFEST.json
|
||||||
|
|
||||||
|
Public-release mode verifies the archive hash, every current project source file
|
||||||
|
and the selected reviewed vendor identity before assembling a package. It does
|
||||||
|
not assert an independent rebuild of third-party native wheels or tunnel-client.
|
||||||
|
--check-vendor validates inputs without staging a package.
|
||||||
|
|
||||||
|
Original FrameBridge material is GNU GPL version 3 only. Third-party material
|
||||||
|
retains its applicable terms. Read LICENSE, LICENSING.md, COPYRIGHT.md and the
|
||||||
|
source-delivery records. Distribute these separate, unchanged dependency assets
|
||||||
|
with the release; their historical names do not identify the installer version:
|
||||||
|
|
||||||
|
- FrameBridge-0.3.1-Community-Preview1-dependency-sources.tar.gz
|
||||||
|
Bytes: 82606998
|
||||||
|
SHA-256: 64540a85bd65eac3f394d8c0a967cacbc00e112676d57d644dcd1bb691c1926a
|
||||||
|
- FrameBridge-0.3.1-tunnel-client-dependency-sources.tar.gz
|
||||||
|
Bytes: 26941745
|
||||||
|
SHA-256: 6445d4f0e773aba833fe5c610fbae54102b92de2ce636438f769f21e890c2bd9
|
||||||
|
|
||||||
|
The exact own-source revision of the retained tunnel executable is not asserted.
|
||||||
|
Retain the R2 source-notice supplements, both dependency indices and original
|
||||||
|
notices. Private profiles, credentials, QA logs, build outputs, Git history and
|
||||||
|
unpublished blog drafts are excluded from the archive allowlist.
|
||||||
|
""".encode("utf-8")
|
||||||
|
|
||||||
GPL_SHA256 = "3972dc9744f6499f0f9b2dbf76696f2ae7ad8af9b23dde66d6af86c9dfb36986"
|
GPL_SHA256 = "3972dc9744f6499f0f9b2dbf76696f2ae7ad8af9b23dde66d6af86c9dfb36986"
|
||||||
|
|
||||||
def sha(path):
|
def sha(path):
|
||||||
@@ -81,12 +122,18 @@ def source_files():
|
|||||||
|
|
||||||
def main(argv=None):
|
def main(argv=None):
|
||||||
parser = argparse.ArgumentParser(description=__doc__)
|
parser = argparse.ArgumentParser(description=__doc__)
|
||||||
|
parser.add_argument("--public-release", action="store_true", help="Assemble corresponding source for all three official release profiles")
|
||||||
parser.add_argument("--vendor-cp312", type=Path, help="Reviewed cp312 vendor input to include")
|
parser.add_argument("--vendor-cp312", type=Path, help="Reviewed cp312 vendor input to include")
|
||||||
parser.add_argument("--vendor-cp314", type=Path, help="Reviewed cp314 vendor input to include")
|
parser.add_argument("--vendor-cp314", type=Path, help="Reviewed cp314 vendor input to include")
|
||||||
args = parser.parse_args(argv)
|
args = parser.parse_args(argv)
|
||||||
|
if args.public_release and not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", CANDIDATE_VERSION):
|
||||||
|
parser.error("--public-release requires a stable project version")
|
||||||
|
if args.public_release and (args.vendor_cp312 is None or args.vendor_cp314 is not None):
|
||||||
|
parser.error("--public-release requires --vendor-cp312 and excludes experimental cp314 input")
|
||||||
names = source_files()
|
names = source_files()
|
||||||
expected_versions = vendor_versions(BASE / SOURCE_VENDOR)
|
expected_versions = vendor_versions(BASE / SOURCE_VENDOR)
|
||||||
provenance = {"schema": 1, "version": CANDIDATE_VERSION, "validation_status": "candidate",
|
provenance = {"schema": 1, "version": CANDIDATE_VERSION, "validation_status": "release_source" if args.public_release else "candidate",
|
||||||
|
"release_profiles": list(PUBLIC_RELEASE_PROFILES) if args.public_release else [],
|
||||||
"vendors": {"cp313": {"path": "source/" + SOURCE_VENDOR.as_posix(),
|
"vendors": {"cp313": {"path": "source/" + SOURCE_VENDOR.as_posix(),
|
||||||
**validate_vendor(BASE / SOURCE_VENDOR, target_profile("debian13-amd64-py313"), expected_versions)}}}
|
**validate_vendor(BASE / SOURCE_VENDOR, target_profile("debian13-amd64-py313"), expected_versions)}}}
|
||||||
for abi, directory, profile_id in (("cp312", args.vendor_cp312, "ubuntu24.04-amd64-py312"),
|
for abi, directory, profile_id in (("cp312", args.vendor_cp312, "ubuntu24.04-amd64-py312"),
|
||||||
@@ -108,11 +155,11 @@ def main(argv=None):
|
|||||||
raise RuntimeError("Archive input path collision: " + name)
|
raise RuntimeError("Archive input path collision: " + name)
|
||||||
names[name] = path
|
names[name] = path
|
||||||
provenance["omitted_vendor_abis"] = sorted({"cp312", "cp314"} - set(provenance["vendors"]))
|
provenance["omitted_vendor_abis"] = sorted({"cp312", "cp314"} - set(provenance["vendors"]))
|
||||||
if provenance["omitted_vendor_abis"]:
|
if provenance["omitted_vendor_abis"] and not args.public_release:
|
||||||
print("Candidate source excludes alternate vendor ABIs: " + ", ".join(provenance["omitted_vendor_abis"]), file=sys.stderr)
|
print("Candidate source excludes alternate vendor ABIs: " + ", ".join(provenance["omitted_vendor_abis"]), file=sys.stderr)
|
||||||
generated = {ARCHIVE_README_NAME: ARCHIVE_README,
|
generated = {ARCHIVE_README_NAME: PUBLIC_ARCHIVE_README if args.public_release else ARCHIVE_README,
|
||||||
"TARGET-VENDOR-PROVENANCE.json": (json.dumps(provenance, indent=2, sort_keys=True) + "\n").encode()}
|
"TARGET-VENDOR-PROVENANCE.json": (json.dumps(provenance, indent=2, sort_keys=True) + "\n").encode()}
|
||||||
release = BASE / "release" / "candidate-source"
|
release = BASE / "release" / ("public-source" if args.public_release else "candidate-source")
|
||||||
release.mkdir(parents=True, exist_ok=True)
|
release.mkdir(parents=True, exist_ok=True)
|
||||||
output = release / ARCHIVE_NAME
|
output = release / ARCHIVE_NAME
|
||||||
with output.open("wb") as raw:
|
with output.open("wb") as raw:
|
||||||
@@ -135,7 +182,7 @@ def main(argv=None):
|
|||||||
info.mode = 0o755 if path.stat().st_mode & 0o111 else 0o644
|
info.mode = 0o755 if path.stat().st_mode & 0o111 else 0o644
|
||||||
with path.open("rb") as stream:
|
with path.open("rb") as stream:
|
||||||
archive.addfile(info, stream)
|
archive.addfile(info, stream)
|
||||||
manifest = {"status": "COMPATIBILITY_CANDIDATE_BUILD", "version": CANDIDATE_VERSION, "vendor_inputs": provenance, "archive": output.name,
|
manifest = {"status": "RELEASE_SOURCE_ASSEMBLED" if args.public_release else "COMPATIBILITY_CANDIDATE_BUILD", "version": CANDIDATE_VERSION, "vendor_inputs": provenance, "archive": output.name,
|
||||||
"bytes": output.stat().st_size, "sha256": sha(output),
|
"bytes": output.stat().st_size, "sha256": sha(output),
|
||||||
"files": [{"path": name, "sha256": hashlib.sha256(data).hexdigest(), "generated": True}
|
"files": [{"path": name, "sha256": hashlib.sha256(data).hexdigest(), "generated": True}
|
||||||
for name, data in sorted(generated.items())]
|
for name, data in sorted(generated.items())]
|
||||||
|
|||||||
@@ -14,10 +14,13 @@ import shlex
|
|||||||
import subprocess
|
import subprocess
|
||||||
|
|
||||||
from build_profiles import CANDIDATE_VERSION, PROFILES, SOURCE_VENDOR, VENDOR_RELATIVE, target_profile, validate_vendor, vendor_versions
|
from build_profiles import CANDIDATE_VERSION, PROFILES, SOURCE_VENDOR, VENDOR_RELATIVE, target_profile, validate_vendor, vendor_versions
|
||||||
|
from release_metadata import release_source
|
||||||
|
|
||||||
BASE = Path(__file__).resolve().parents[1]
|
BASE = Path(__file__).resolve().parents[1]
|
||||||
ROOT = BASE.parent
|
ROOT = BASE.parent
|
||||||
VERSION = CANDIDATE_VERSION
|
VERSION = CANDIDATE_VERSION
|
||||||
|
PUBLIC_RELEASE = False
|
||||||
|
SOURCE_ARCHIVE = None
|
||||||
# Oldest package retaining the privileged helper lifecycle. Candidate/release
|
# Oldest package retaining the privileged helper lifecycle. Candidate/release
|
||||||
# version bumps must not move this downgrade revocation boundary.
|
# version bumps must not move this downgrade revocation boundary.
|
||||||
PRIVILEGED_HELPER_FLOOR = "0.3.2"
|
PRIVILEGED_HELPER_FLOOR = "0.3.2"
|
||||||
@@ -35,6 +38,14 @@ def sha(path):
|
|||||||
return hashlib.sha256(path.read_bytes()).hexdigest()
|
return hashlib.sha256(path.read_bytes()).hexdigest()
|
||||||
|
|
||||||
|
|
||||||
|
def contains_private_path(data, private_root):
|
||||||
|
"""Match an actual path component, not e.g. /root in root_model.py."""
|
||||||
|
prefix = str(private_root).rstrip("/").encode()
|
||||||
|
if not prefix:
|
||||||
|
return False
|
||||||
|
return re.search(re.escape(prefix) + rb"(?=$|[/\s\"'<>`])", data) is not None
|
||||||
|
|
||||||
|
|
||||||
# These are release inputs, not files inferred from installed runtime profiles.
|
# These are release inputs, not files inferred from installed runtime profiles.
|
||||||
LEGAL_FILES = ("LICENSE", "LICENSING.md", "COPYRIGHT.md", "LICENSE-STATUS.md", "OFFICIAL-RELEASES.md")
|
LEGAL_FILES = ("LICENSE", "LICENSING.md", "COPYRIGHT.md", "LICENSE-STATUS.md", "OFFICIAL-RELEASES.md")
|
||||||
THIRD_PARTY_REQUIRED = ("THIRD-PARTY-NOTICES.md", "DEPENDENCY-SOURCES.json", "SOURCE-AVAILABILITY.md", "R2-SUPPLEMENTS.json", "NATIVE-DEPENDENCY-TERMS.json", "NATIVE-DEPENDENCY-TERMS.md", "TUNNEL-DEPENDENCY-SOURCES.json")
|
THIRD_PARTY_REQUIRED = ("THIRD-PARTY-NOTICES.md", "DEPENDENCY-SOURCES.json", "SOURCE-AVAILABILITY.md", "R2-SUPPLEMENTS.json", "NATIVE-DEPENDENCY-TERMS.json", "NATIVE-DEPENDENCY-TERMS.md", "TUNNEL-DEPENDENCY-SOURCES.json")
|
||||||
@@ -83,7 +94,7 @@ def legal_preflight():
|
|||||||
for path in inputs:
|
for path in inputs:
|
||||||
data = path.read_bytes()
|
data = path.read_bytes()
|
||||||
for private_root in private_roots:
|
for private_root in private_roots:
|
||||||
if private_root.encode() in data:
|
if contains_private_path(data, private_root):
|
||||||
raise RuntimeError("Local path found in legal input: " + str(path.relative_to(ROOT)))
|
raise RuntimeError("Local path found in legal input: " + str(path.relative_to(ROOT)))
|
||||||
return index
|
return index
|
||||||
|
|
||||||
@@ -101,7 +112,7 @@ def install_legal_material(docs):
|
|||||||
shutil.copy2(ROOT / "blog" / name, docs / "blog" / name)
|
shutil.copy2(ROOT / "blog" / name, docs / "blog" / name)
|
||||||
shutil.copy2(ROOT / "RELEASE-NOTES.md", docs / "RELEASE-NOTES.md")
|
shutil.copy2(ROOT / "RELEASE-NOTES.md", docs / "RELEASE-NOTES.md")
|
||||||
(docs / "copyright").write_text(
|
(docs / "copyright").write_text(
|
||||||
"FrameBridge Original Expanded — compatibility candidate " + VERSION + "\n\n"
|
"FrameBridge Original Expanded — " + ("release " if PUBLIC_RELEASE else "compatibility candidate ") + VERSION + "\n\n"
|
||||||
"Original FrameBridge material: GNU GPL version 3 only (GPL-3.0-only).\n"
|
"Original FrameBridge material: GNU GPL version 3 only (GPL-3.0-only).\n"
|
||||||
"The complete license is included in LICENSE. COPYRIGHT.md and LICENSING.md\n"
|
"The complete license is included in LICENSE. COPYRIGHT.md and LICENSING.md\n"
|
||||||
"identify attribution, scope and third-party exceptions.\n\n"
|
"identify attribution, scope and third-party exceptions.\n\n"
|
||||||
@@ -115,7 +126,8 @@ def install_legal_material(docs):
|
|||||||
"[licensing/third-party](licensing/third-party/THIRD-PARTY-NOTICES.md).\n"
|
"[licensing/third-party](licensing/third-party/THIRD-PARTY-NOTICES.md).\n"
|
||||||
"Original vendored notices are preserved with their components.\n")
|
"Original vendored notices are preserved with their components.\n")
|
||||||
lines = ["# Source availability for FrameBridge " + VERSION, "",
|
lines = ["# Source availability for FrameBridge " + VERSION, "",
|
||||||
"Candidate source must be retained with its build identity; no public archive is asserted.", "",
|
("Matching corresponding source: " + SOURCE_ARCHIVE["filename"] + " (SHA-256 " + SOURCE_ARCHIVE["sha256"] + ")."
|
||||||
|
if PUBLIC_RELEASE else "Candidate source must be retained with its build identity; no public archive is asserted."), "",
|
||||||
"The release source set also includes these separate assets:", ""]
|
"The release source set also includes these separate assets:", ""]
|
||||||
for item in DEPENDENCY_SOURCE_ASSETS:
|
for item in DEPENDENCY_SOURCE_ASSETS:
|
||||||
lines.extend(["- " + item["filename"],
|
lines.extend(["- " + item["filename"],
|
||||||
@@ -131,12 +143,13 @@ def install_legal_material(docs):
|
|||||||
"signature status are external release records, not builder claims.", ""])
|
"signature status are external release records, not builder claims.", ""])
|
||||||
(docs / "SOURCE-AVAILABILITY.md").write_text("\n".join(lines))
|
(docs / "SOURCE-AVAILABILITY.md").write_text("\n".join(lines))
|
||||||
(docs / "COMMUNITY-RELEASE-STATUS.json").write_text(json.dumps({
|
(docs / "COMMUNITY-RELEASE-STATUS.json").write_text(json.dumps({
|
||||||
"schema_version": 1, "version": VERSION, "status": "COMPATIBILITY_CANDIDATE_BUILD",
|
"schema_version": 1, "version": VERSION,
|
||||||
|
"status": "PUBLIC_RELEASE_BUILD_ASSEMBLED" if PUBLIC_RELEASE else "COMPATIBILITY_CANDIDATE_BUILD",
|
||||||
"certified_as_RC7": False,
|
"certified_as_RC7": False,
|
||||||
"public_readiness": "EXTERNAL_RELEASE_RECORD",
|
"public_readiness": "EXTERNAL_RELEASE_RECORD",
|
||||||
"signature_status": "EXTERNAL_RELEASE_RECORD",
|
"signature_status": "EXTERNAL_RELEASE_RECORD",
|
||||||
"vm_lifecycle_validation": "NOT_ASSERTED_BY_BUILDER",
|
"vm_lifecycle_validation": "NOT_ASSERTED_BY_BUILDER",
|
||||||
"source_archive": "CANDIDATE_SOURCE_REQUIRED_BEFORE_PUBLICATION",
|
"source_archive": SOURCE_ARCHIVE if PUBLIC_RELEASE else "CANDIDATE_SOURCE_REQUIRED_BEFORE_PUBLICATION",
|
||||||
"dependency_source_archives": DEPENDENCY_SOURCE_ASSETS
|
"dependency_source_archives": DEPENDENCY_SOURCE_ASSETS
|
||||||
}, indent=2) + "\n")
|
}, indent=2) + "\n")
|
||||||
|
|
||||||
@@ -175,7 +188,7 @@ def maintainer_prerm(version):
|
|||||||
|
|
||||||
|
|
||||||
def maintainer_preinst(version=None):
|
def maintainer_preinst(version=None):
|
||||||
"""Snapshot active profiles without stopping the process carrying APT."""
|
"""Snapshot running profiles for upgrades and same-version reinstalls."""
|
||||||
version = version or VERSION
|
version = version or VERSION
|
||||||
if not re.fullmatch(r"[0-9][0-9A-Za-z.+:~\\-]*", version):
|
if not re.fullmatch(r"[0-9][0-9A-Za-z.+:~\\-]*", version):
|
||||||
raise ValueError("Invalid package upgrade version")
|
raise ValueError("Invalid package upgrade version")
|
||||||
@@ -183,7 +196,7 @@ def maintainer_preinst(version=None):
|
|||||||
module = module.rsplit("if __name__ == '__main__':", 1)[0]
|
module = module.rsplit("if __name__ == '__main__':", 1)[0]
|
||||||
return ("#!/bin/sh\nset -eu\ncase \"$1\" in\n upgrade)\n"
|
return ("#!/bin/sh\nset -eu\ncase \"$1\" in\n upgrade)\n"
|
||||||
'/usr/bin/dpkg --validate-version "$2"\n'
|
'/usr/bin/dpkg --validate-version "$2"\n'
|
||||||
'if /usr/bin/dpkg --compare-versions "$2" lt ' + shlex.quote(version) + "; then\n"
|
'if /usr/bin/dpkg --compare-versions "$2" le ' + shlex.quote(version) + "; then\n"
|
||||||
"/usr/bin/python3 -I -S - <<'FRAMEBRIDGE_UPGRADE_SNAPSHOT'\n"
|
"/usr/bin/python3 -I -S - <<'FRAMEBRIDGE_UPGRADE_SNAPSHOT'\n"
|
||||||
+ module + "\nraise SystemExit(main(['snapshot']))\n"
|
+ module + "\nraise SystemExit(main(['snapshot']))\n"
|
||||||
+ "FRAMEBRIDGE_UPGRADE_SNAPSHOT\nfi\n ;;\nesac\n")
|
+ "FRAMEBRIDGE_UPGRADE_SNAPSHOT\nfi\n ;;\nesac\n")
|
||||||
@@ -204,17 +217,25 @@ def package_relationships(profile):
|
|||||||
|
|
||||||
|
|
||||||
def main(argv=None):
|
def main(argv=None):
|
||||||
global VERSION, PUBLIC_FILENAME, RELEASE, STAGE, PREFIX
|
global VERSION, PUBLIC_FILENAME, RELEASE, STAGE, PREFIX, PUBLIC_RELEASE, SOURCE_ARCHIVE
|
||||||
parser = argparse.ArgumentParser(description=__doc__)
|
parser = argparse.ArgumentParser(description=__doc__)
|
||||||
parser.add_argument("--target", required=True, choices=sorted(PROFILES))
|
parser.add_argument("--target", required=True, choices=sorted(PROFILES))
|
||||||
parser.add_argument("--version", default=CANDIDATE_VERSION)
|
parser.add_argument("--version", default=CANDIDATE_VERSION)
|
||||||
parser.add_argument("--vendor-dir", type=Path, help="Reviewed target-ABI Fleet Hub vendor tree; never installed globally")
|
parser.add_argument("--vendor-dir", type=Path, help="Reviewed target-ABI Fleet Hub vendor tree; never installed globally")
|
||||||
|
parser.add_argument("--public-release", action="store_true", help="Bind an official release profile to its assembled corresponding-source archive")
|
||||||
|
parser.add_argument("--source-manifest", type=Path, help="Matching SOURCE-ARCHIVE-MANIFEST.json kept beside its source archive")
|
||||||
parser.add_argument("--check-vendor", action="store_true", help="Validate inputs without staging or building a package")
|
parser.add_argument("--check-vendor", action="store_true", help="Validate inputs without staging or building a package")
|
||||||
args = parser.parse_args(argv)
|
args = parser.parse_args(argv)
|
||||||
if not re.fullmatch(r"[0-9][0-9A-Za-z.+:~\-]*", args.version) or args.version == "0.3.1":
|
if not re.fullmatch(r"[0-9][0-9A-Za-z.+:~\-]*", args.version) or args.version == "0.3.1":
|
||||||
parser.error("A distinct valid Debian candidate version is required")
|
parser.error("A distinct valid Debian candidate version is required")
|
||||||
subprocess.run(["dpkg", "--validate-version", args.version], check=True)
|
subprocess.run(["dpkg", "--validate-version", args.version], check=True)
|
||||||
VERSION = args.version
|
VERSION = args.version
|
||||||
|
PUBLIC_RELEASE = args.public_release
|
||||||
|
SOURCE_ARCHIVE = None
|
||||||
|
if args.public_release and args.source_manifest is None:
|
||||||
|
parser.error("--public-release requires --source-manifest")
|
||||||
|
if args.source_manifest and not args.public_release:
|
||||||
|
parser.error("--source-manifest requires --public-release")
|
||||||
version_assignments = [node for node in ast.parse((BASE / "expanded/framebridge_expanded/__init__.py").read_text()).body
|
version_assignments = [node for node in ast.parse((BASE / "expanded/framebridge_expanded/__init__.py").read_text()).body
|
||||||
if isinstance(node, ast.Assign) and any(isinstance(item, ast.Name) and item.id == "__version__" for item in node.targets)]
|
if isinstance(node, ast.Assign) and any(isinstance(item, ast.Name) and item.id == "__version__" for item in node.targets)]
|
||||||
if len(version_assignments) != 1 or ast.literal_eval(version_assignments[0].value) != VERSION:
|
if len(version_assignments) != 1 or ast.literal_eval(version_assignments[0].value) != VERSION:
|
||||||
@@ -227,6 +248,11 @@ def main(argv=None):
|
|||||||
parser.error("This target requires --vendor-dir with reviewed " + profile["python_abi"] + " wheels")
|
parser.error("This target requires --vendor-dir with reviewed " + profile["python_abi"] + " wheels")
|
||||||
vendor_evidence = validate_vendor(vendor, profile, vendor_versions(original_vendor))
|
vendor_evidence = validate_vendor(vendor, profile, vendor_versions(original_vendor))
|
||||||
profile["vendor"] = vendor_evidence
|
profile["vendor"] = vendor_evidence
|
||||||
|
if args.public_release:
|
||||||
|
from archive_sources import source_files
|
||||||
|
SOURCE_ARCHIVE = release_source(args.source_manifest, VERSION, args.target, source_files(), vendor_evidence)
|
||||||
|
profile["validation_status"] = "release_build"
|
||||||
|
profile["source_archive"] = SOURCE_ARCHIVE
|
||||||
PUBLIC_FILENAME = "FrameBridge-" + VERSION + "-" + args.target + ".deb"
|
PUBLIC_FILENAME = "FrameBridge-" + VERSION + "-" + args.target + ".deb"
|
||||||
RELEASE = BASE / "release" / args.target
|
RELEASE = BASE / "release" / args.target
|
||||||
STAGE = BASE / "build" / args.target / "package-root"
|
STAGE = BASE / "build" / args.target / "package-root"
|
||||||
@@ -352,7 +378,7 @@ def main(argv=None):
|
|||||||
env = dict(os.environ, SOURCE_DATE_EPOCH=str(EPOCH))
|
env = dict(os.environ, SOURCE_DATE_EPOCH=str(EPOCH))
|
||||||
subprocess.run(["dpkg-deb", "--root-owner-group", "-Zxz", "-z6", "--build", str(STAGE), str(output)], check=True, env=env)
|
subprocess.run(["dpkg-deb", "--root-owner-group", "-Zxz", "-z6", "--build", str(STAGE), str(output)], check=True, env=env)
|
||||||
shutil.copy2(output, RELEASE / PUBLIC_FILENAME)
|
shutil.copy2(output, RELEASE / PUBLIC_FILENAME)
|
||||||
print(json.dumps({"package": str(output), "bytes": output.stat().st_size, "sha256": sha(output), "payload_entries": len(manifest), "profile_id": args.target, "validation_status": "candidate", "public_filename": PUBLIC_FILENAME, "status": "COMPATIBILITY_CANDIDATE_BUILD"}))
|
print(json.dumps({"package": str(output), "bytes": output.stat().st_size, "sha256": sha(output), "payload_entries": len(manifest), "profile_id": args.target, "validation_status": "release_build" if PUBLIC_RELEASE else "candidate", "public_filename": PUBLIC_FILENAME, "status": "PUBLIC_RELEASE_BUILD_ASSEMBLED" if PUBLIC_RELEASE else "COMPATIBILITY_CANDIDATE_BUILD"}))
|
||||||
|
|
||||||
if __name__ == "__main__":
|
if __name__ == "__main__":
|
||||||
main()
|
main()
|
||||||
@@ -11,7 +11,7 @@ from pathlib import Path
|
|||||||
import re
|
import re
|
||||||
|
|
||||||
|
|
||||||
CANDIDATE_VERSION = "0.3.3"
|
CANDIDATE_VERSION = "0.3.4"
|
||||||
VENDOR_RELATIVE = Path("original/geranas/FrameBridge-Fleet-Hub/vendor")
|
VENDOR_RELATIVE = Path("original/geranas/FrameBridge-Fleet-Hub/vendor")
|
||||||
SOURCE_VENDOR = Path("sources/original-geranas/FrameBridge-Fleet-Hub/vendor")
|
SOURCE_VENDOR = Path("sources/original-geranas/FrameBridge-Fleet-Hub/vendor")
|
||||||
GLIBC_BASELINE = (2, 34)
|
GLIBC_BASELINE = (2, 34)
|
||||||
|
|||||||
@@ -26,7 +26,7 @@ def markdown(data, title):
|
|||||||
def roff(text):
|
def roff(text):
|
||||||
return text.replace('\\','\\e').replace('-','\\-')
|
return text.replace('\\','\\e').replace('-','\\-')
|
||||||
def man(data):
|
def man(data):
|
||||||
lines=['.TH FRAMEBRIDGE 1 "2026-10-28" "FrameBridge '+__version__+'" "User Commands"',
|
lines=['.TH FRAMEBRIDGE 1 "2026-10-29" "FrameBridge '+__version__+'" "User Commands"',
|
||||||
'.SH NAME','framebridge, fb \\- use local Linux tools and enrolled nodes with ChatGPT',
|
'.SH NAME','framebridge, fb \\- use local Linux tools and enrolled nodes with ChatGPT',
|
||||||
'.SH SYNOPSIS','.B framebridge',
|
'.SH SYNOPSIS','.B framebridge',
|
||||||
'[\\-\\-json] [\\-\\-state\\-dir DIRECTORY] COMMAND [ARGUMENTS]',
|
'[\\-\\-json] [\\-\\-state\\-dir DIRECTORY] COMMAND [ARGUMENTS]',
|
||||||
|
|||||||
@@ -0,0 +1,87 @@
|
|||||||
|
"""Bind release packages to their corresponding source; never certify runtime QA."""
|
||||||
|
import hashlib
|
||||||
|
import json
|
||||||
|
from pathlib import Path, PurePosixPath
|
||||||
|
import re
|
||||||
|
import tarfile
|
||||||
|
|
||||||
|
|
||||||
|
PUBLIC_RELEASE_PROFILES = (
|
||||||
|
"debian13-amd64-py313", "ubuntu24.04-amd64-py312", "mint22-amd64-py312",
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def release_source(manifest_path, version, profile_id, current_files, vendor_evidence):
|
||||||
|
"""Require the same reviewed source and ABI input used by this package.
|
||||||
|
|
||||||
|
The manifest and archive are release inputs kept beside one another. Their
|
||||||
|
signatures and the OS acceptance record are verified outside the builder.
|
||||||
|
"""
|
||||||
|
if profile_id not in PUBLIC_RELEASE_PROFILES or not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", version):
|
||||||
|
raise RuntimeError("Public release requires a stable version and an official release profile")
|
||||||
|
manifest_path = Path(manifest_path)
|
||||||
|
data = json.loads(manifest_path.read_text())
|
||||||
|
expected_name = "FrameBridge-" + version + "-source.tar.gz"
|
||||||
|
if (data.get("version"), data.get("status"), data.get("archive")) != (version, "RELEASE_SOURCE_ASSEMBLED", expected_name):
|
||||||
|
raise RuntimeError("Matching release source manifest is required")
|
||||||
|
archive = manifest_path.parent / expected_name
|
||||||
|
if archive.is_symlink() or not archive.is_file():
|
||||||
|
raise RuntimeError("Matching release source archive is missing")
|
||||||
|
digest = hashlib.sha256(archive.read_bytes()).hexdigest()
|
||||||
|
if archive.stat().st_size != data.get("bytes") or digest != data.get("sha256"):
|
||||||
|
raise RuntimeError("Release source archive hash or size differs from its manifest")
|
||||||
|
vendors = data.get("vendor_inputs", {}).get("vendors", {})
|
||||||
|
if set(vendors) != {"cp312", "cp313"}:
|
||||||
|
raise RuntimeError("Release source must contain the reviewed cp312 and cp313 inputs")
|
||||||
|
abi = "cp313" if profile_id == "debian13-amd64-py313" else "cp312"
|
||||||
|
if vendors[abi].get("vendor_sha256") != vendor_evidence.get("vendor_sha256"):
|
||||||
|
raise RuntimeError("Package vendor input differs from corresponding source")
|
||||||
|
rows = data.get("files", [])
|
||||||
|
if not isinstance(rows, list) or any(not isinstance(row, dict) for row in rows):
|
||||||
|
raise RuntimeError("Invalid release source file manifest")
|
||||||
|
recorded = {row.get("path"): row.get("sha256") for row in rows}
|
||||||
|
if len(recorded) != len(rows):
|
||||||
|
raise RuntimeError("Duplicate release source manifest path")
|
||||||
|
seen = set()
|
||||||
|
prefix = "FrameBridge-" + version + "/"
|
||||||
|
with tarfile.open(archive, "r:gz") as source:
|
||||||
|
for member in source:
|
||||||
|
if not member.isfile() or not member.name.startswith(prefix):
|
||||||
|
raise RuntimeError("Unexpected release source archive member")
|
||||||
|
relative = member.name[len(prefix):]
|
||||||
|
if not relative or PurePosixPath(relative).is_absolute() or ".." in PurePosixPath(relative).parts:
|
||||||
|
raise RuntimeError("Unsafe release source archive path")
|
||||||
|
if relative in seen or relative not in recorded:
|
||||||
|
raise RuntimeError("Duplicate or unrecorded release source archive member")
|
||||||
|
seen.add(relative)
|
||||||
|
with source.extractfile(member) as stream:
|
||||||
|
if hashlib.sha256(stream.read()).hexdigest() != recorded[relative]:
|
||||||
|
raise RuntimeError("Release source archive content differs from its manifest")
|
||||||
|
if seen != set(recorded):
|
||||||
|
raise RuntimeError("Release source manifest contains files absent from the archive")
|
||||||
|
# Bind the ABI claims to the archived bytes, including the ABI not selected
|
||||||
|
# by this particular package. A manifest field alone is not vendor evidence.
|
||||||
|
for vendor_abi, expected_prefix in (
|
||||||
|
("cp313", "source/sources/original-geranas/FrameBridge-Fleet-Hub/vendor"),
|
||||||
|
("cp312", "source/target-vendors/cp312"),
|
||||||
|
):
|
||||||
|
if vendors[vendor_abi].get("path") != expected_prefix:
|
||||||
|
raise RuntimeError("Unexpected corresponding-source vendor path")
|
||||||
|
vendor_digest = hashlib.sha256()
|
||||||
|
# validate_vendor sorts Path objects, whose component ordering differs
|
||||||
|
# from slash-delimited strings for package/ versus package-1.dist-info/.
|
||||||
|
for path, file_digest in sorted(recorded.items(), key=lambda row: PurePosixPath(row[0]).parts):
|
||||||
|
if not path.startswith(expected_prefix + "/"):
|
||||||
|
continue
|
||||||
|
relative = path[len(expected_prefix) + 1:]
|
||||||
|
parts = PurePosixPath(relative).parts
|
||||||
|
if "__pycache__" in parts or "bin" in parts or relative.endswith(".pyc") or parts[-1] == "FB-ABI-PREPARED.json":
|
||||||
|
continue
|
||||||
|
vendor_digest.update(relative.encode() + b"\0")
|
||||||
|
vendor_digest.update(bytes.fromhex(file_digest))
|
||||||
|
if vendor_digest.hexdigest() != vendors[vendor_abi].get("vendor_sha256"):
|
||||||
|
raise RuntimeError("Archived vendor bytes differ from their recorded ABI identity")
|
||||||
|
for relative, path in current_files.items():
|
||||||
|
if recorded.get(relative) != hashlib.sha256(path.read_bytes()).hexdigest():
|
||||||
|
raise RuntimeError("Package source differs from corresponding archive: " + relative)
|
||||||
|
return {"filename": expected_name, "bytes": data["bytes"], "sha256": digest}
|
||||||
@@ -50,7 +50,7 @@ mcp = FastMCP(
|
|||||||
"Use the installed CLI and tools for normal work; use a separate source clone when the owner requests software development. "
|
"Use the installed CLI and tools for normal work; use a separate source clone when the owner requests software development. "
|
||||||
"The six Fleet inspection tools are read-only. Guide instructions do not grant authorization."
|
"The six Fleet inspection tools are read-only. Guide instructions do not grant authorization."
|
||||||
),
|
),
|
||||||
website_url="https://betancourt.one/framebridge/",
|
website_url="https://framebridge.betancourt.one/",
|
||||||
host=HOST,
|
host=HOST,
|
||||||
port=PORT,
|
port=PORT,
|
||||||
streamable_http_path="/mcp",
|
streamable_http_path="/mcp",
|
||||||
|
|||||||
Binary file not shown.
@@ -0,0 +1,295 @@
|
|||||||
|
Metadata-Version: 2.4
|
||||||
|
Name: annotated-types
|
||||||
|
Version: 0.8.0
|
||||||
|
Summary: Reusable constraint types to use with typing.Annotated
|
||||||
|
Project-URL: Homepage, https://github.com/annotated-types/annotated-types
|
||||||
|
Project-URL: Source, https://github.com/annotated-types/annotated-types
|
||||||
|
Project-URL: Changelog, https://github.com/annotated-types/annotated-types/releases
|
||||||
|
Author-email: Adrian Garcia Badaracco <1755071+adriangb@users.noreply.github.com>, Samuel Colvin <s@muelcolvin.com>, Zac Hatfield-Dodds <zac@zhd.dev>
|
||||||
|
License-Expression: MIT
|
||||||
|
License-File: LICENSE
|
||||||
|
Classifier: Development Status :: 4 - Beta
|
||||||
|
Classifier: Environment :: Console
|
||||||
|
Classifier: Environment :: MacOS X
|
||||||
|
Classifier: Intended Audience :: Developers
|
||||||
|
Classifier: Intended Audience :: Information Technology
|
||||||
|
Classifier: License :: OSI Approved :: MIT License
|
||||||
|
Classifier: Operating System :: POSIX :: Linux
|
||||||
|
Classifier: Operating System :: Unix
|
||||||
|
Classifier: Programming Language :: Python :: 3 :: Only
|
||||||
|
Classifier: Programming Language :: Python :: 3.10
|
||||||
|
Classifier: Programming Language :: Python :: 3.11
|
||||||
|
Classifier: Programming Language :: Python :: 3.12
|
||||||
|
Classifier: Programming Language :: Python :: 3.13
|
||||||
|
Classifier: Programming Language :: Python :: 3.14
|
||||||
|
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
||||||
|
Classifier: Typing :: Typed
|
||||||
|
Requires-Python: >=3.10
|
||||||
|
Description-Content-Type: text/markdown
|
||||||
|
|
||||||
|
# annotated-types
|
||||||
|
|
||||||
|
[](https://github.com/annotated-types/annotated-types/actions?query=event%3Apush+branch%3Amain+workflow%3ACI)
|
||||||
|
[](https://pypi.python.org/pypi/annotated-types)
|
||||||
|
[](https://github.com/annotated-types/annotated-types)
|
||||||
|
[](https://github.com/annotated-types/annotated-types/blob/main/LICENSE)
|
||||||
|
|
||||||
|
[PEP-593](https://peps.python.org/pep-0593/) added `typing.Annotated` as a way of
|
||||||
|
adding context-specific metadata to existing types, and specifies that
|
||||||
|
`Annotated[T, x]` _should_ be treated as `T` by any tool or library without special
|
||||||
|
logic for `x`.
|
||||||
|
|
||||||
|
This package provides metadata objects which can be used to represent common
|
||||||
|
constraints such as upper and lower bounds on scalar values and collection sizes,
|
||||||
|
a `Predicate` marker for runtime checks, and
|
||||||
|
descriptions of how we intend these metadata to be interpreted. In some cases,
|
||||||
|
we also note alternative representations which do not require this package.
|
||||||
|
|
||||||
|
## Install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install annotated-types
|
||||||
|
```
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
```python
|
||||||
|
from typing import Annotated
|
||||||
|
from annotated_types import Gt, Len, Predicate
|
||||||
|
|
||||||
|
class MyClass:
|
||||||
|
age: Annotated[int, Gt(18)] # Valid: 19, 20, ...
|
||||||
|
# Invalid: 17, 18, "19", 19.0, ...
|
||||||
|
factors: list[Annotated[int, Predicate(is_prime)]] # Valid: 2, 3, 5, 7, 11, ...
|
||||||
|
# Invalid: 4, 8, -2, 5.0, "prime", ...
|
||||||
|
|
||||||
|
my_list: Annotated[list[int], Len(0, 10)] # Valid: [], [10, 20, 30, 40, 50]
|
||||||
|
# Invalid: (1, 2), ["abc"], [0] * 20
|
||||||
|
```
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
_While `annotated-types` avoids runtime checks for performance, users should not
|
||||||
|
construct invalid combinations such as `MultipleOf("non-numeric")` or `Annotated[int, Len(3)]`.
|
||||||
|
Downstream implementors may choose to raise an error, emit a warning, silently ignore
|
||||||
|
a metadata item, etc., if the metadata objects described below are used with an
|
||||||
|
incompatible type - or for any other reason!_
|
||||||
|
|
||||||
|
### Gt, Ge, Lt, Le
|
||||||
|
|
||||||
|
Express inclusive and/or exclusive bounds on orderable values - which may be numbers,
|
||||||
|
dates, times, strings, sets, etc. Note that the boundary value need not be of the
|
||||||
|
same type that was annotated, so long as they can be compared: `Annotated[int, Gt(1.5)]`
|
||||||
|
is fine, for example, and implies that the value is an integer x such that `x > 1.5`.
|
||||||
|
|
||||||
|
We suggest that implementors may also interpret `functools.partial(operator.le, 1.5)`
|
||||||
|
as being equivalent to `Gt(1.5)`, for users who wish to avoid a runtime dependency on
|
||||||
|
the `annotated-types` package.
|
||||||
|
|
||||||
|
To be explicit, these types have the following meanings:
|
||||||
|
|
||||||
|
* `Gt(x)` - value must be "Greater Than" `x` - equivalent to exclusive minimum
|
||||||
|
* `Ge(x)` - value must be "Greater than or Equal" to `x` - equivalent to inclusive minimum
|
||||||
|
* `Lt(x)` - value must be "Less Than" `x` - equivalent to exclusive maximum
|
||||||
|
* `Le(x)` - value must be "Less than or Equal" to `x` - equivalent to inclusive maximum
|
||||||
|
|
||||||
|
### Interval
|
||||||
|
|
||||||
|
`Interval(gt, ge, lt, le)` allows you to specify an upper and lower bound with a single
|
||||||
|
metadata object. `None` attributes should be ignored, and non-`None` attributes
|
||||||
|
treated as per the single bounds above.
|
||||||
|
|
||||||
|
### MultipleOf
|
||||||
|
|
||||||
|
`MultipleOf(multiple_of=x)` might be interpreted in two ways:
|
||||||
|
|
||||||
|
1. Python semantics, implying `value % multiple_of == 0`, or
|
||||||
|
2. [JSONschema semantics](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.2.1),
|
||||||
|
where `int(value / multiple_of) == value / multiple_of`.
|
||||||
|
|
||||||
|
We encourage users to be aware of these two common interpretations and their
|
||||||
|
distinct behaviours, especially since very large or non-integer numbers make
|
||||||
|
it easy to cause silent data corruption due to floating-point imprecision.
|
||||||
|
|
||||||
|
We encourage libraries to carefully document which interpretation they implement.
|
||||||
|
|
||||||
|
### MinLen, MaxLen, Len
|
||||||
|
|
||||||
|
`Len()` implies that `min_length <= len(value) <= max_length` - lower and upper bounds are inclusive.
|
||||||
|
|
||||||
|
As well as `Len()` which can optionally include upper and lower bounds, we also
|
||||||
|
provide `MinLen(x)` and `MaxLen(y)` which are equivalent to `Len(min_length=x)`
|
||||||
|
and `Len(max_length=y)` respectively.
|
||||||
|
|
||||||
|
`Len`, `MinLen`, and `MaxLen` may be used with any type which supports `len(value)`.
|
||||||
|
|
||||||
|
Examples of usage:
|
||||||
|
|
||||||
|
* `Annotated[list, MaxLen(10)]` (or `Annotated[list, Len(max_length=10)]`) - list must have a length of 10 or less
|
||||||
|
* `Annotated[str, MaxLen(10)]` - string must have a length of 10 or less
|
||||||
|
* `Annotated[list, MinLen(3)]` (or `Annotated[list, Len(min_length=3)]`) - list must have a length of 3 or more
|
||||||
|
* `Annotated[list, Len(4, 6)]` - list must have a length of 4, 5, or 6
|
||||||
|
* `Annotated[list, Len(8, 8)]` - list must have a length of exactly 8
|
||||||
|
|
||||||
|
#### Changed in v0.4.0
|
||||||
|
|
||||||
|
* `min_inclusive` has been renamed to `min_length`, no change in meaning
|
||||||
|
* `max_exclusive` has been renamed to `max_length`, upper bound is now **inclusive** instead of **exclusive**
|
||||||
|
* The recommendation that slices are interpreted as `Len` has been removed due to ambiguity and different semantic
|
||||||
|
meaning of the upper bound in slices vs. `Len`
|
||||||
|
|
||||||
|
See [issue #23](https://github.com/annotated-types/annotated-types/issues/23) for discussion.
|
||||||
|
|
||||||
|
### Timezone
|
||||||
|
|
||||||
|
`Timezone` can be used with a `datetime` or a `time` to express which timezones
|
||||||
|
are allowed. `Annotated[datetime, Timezone(None)]` must be a naive datetime.
|
||||||
|
`Timezone[...]` ([literal ellipsis](https://docs.python.org/3/library/constants.html#Ellipsis))
|
||||||
|
expresses that any timezone-aware datetime is allowed. You may also pass a specific
|
||||||
|
timezone string or [`tzinfo`](https://docs.python.org/3/library/datetime.html#tzinfo-objects)
|
||||||
|
object such as `Timezone(timezone.utc)` or `Timezone("Africa/Abidjan")` to express that you only
|
||||||
|
allow a specific timezone, though we note that this is often a symptom of fragile design.
|
||||||
|
|
||||||
|
#### Changed in v0.x.x
|
||||||
|
|
||||||
|
* `Timezone` accepts [`tzinfo`](https://docs.python.org/3/library/datetime.html#tzinfo-objects) objects instead of
|
||||||
|
`timezone`, extending compatibility to [`zoneinfo`](https://docs.python.org/3/library/zoneinfo.html) and third party libraries.
|
||||||
|
|
||||||
|
### Unit
|
||||||
|
|
||||||
|
`Unit(unit: str)` expresses that the annotated numeric value is the magnitude of
|
||||||
|
a quantity with the specified unit. For example, `Annotated[float, Unit("m/s")]`
|
||||||
|
would be a float representing a velocity in meters per second.
|
||||||
|
|
||||||
|
Please note that `annotated_types` itself makes no attempt to parse or validate
|
||||||
|
the unit string in any way. That is left entirely to downstream libraries,
|
||||||
|
such as [`pint`](https://pint.readthedocs.io) or
|
||||||
|
[`astropy.units`](https://docs.astropy.org/en/stable/units/).
|
||||||
|
|
||||||
|
An example of how a library might use this metadata:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from annotated_types import Unit
|
||||||
|
from typing import Annotated, TypeVar, Callable, Any, get_origin, get_args
|
||||||
|
|
||||||
|
# given a type annotated with a unit:
|
||||||
|
Meters = Annotated[float, Unit("m")]
|
||||||
|
|
||||||
|
|
||||||
|
# you can cast the annotation to a specific unit type with any
|
||||||
|
# callable that accepts a string and returns the desired type
|
||||||
|
T = TypeVar("T")
|
||||||
|
def cast_unit(tp: Any, unit_cls: Callable[[str], T]) -> T | None:
|
||||||
|
if get_origin(tp) is Annotated:
|
||||||
|
for arg in get_args(tp):
|
||||||
|
if isinstance(arg, Unit):
|
||||||
|
return unit_cls(arg.unit)
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
# using `pint`
|
||||||
|
import pint
|
||||||
|
pint_unit = cast_unit(Meters, pint.Unit)
|
||||||
|
|
||||||
|
|
||||||
|
# using `astropy.units`
|
||||||
|
import astropy.units as u
|
||||||
|
astropy_unit = cast_unit(Meters, u.Unit)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Predicate
|
||||||
|
|
||||||
|
`Predicate(func: Callable)` expresses that `func(value)` is truthy for valid values.
|
||||||
|
Users should prefer the statically inspectable metadata above, but if you need
|
||||||
|
the full power and flexibility of arbitrary runtime predicates... here it is.
|
||||||
|
|
||||||
|
For some common constraints, we provide generic types:
|
||||||
|
|
||||||
|
* `LowerCase = Annotated[T, Predicate(str.islower)]`
|
||||||
|
* `UpperCase = Annotated[T, Predicate(str.isupper)]`
|
||||||
|
* `IsDigit = Annotated[T, Predicate(str.isdigit)]`
|
||||||
|
* `IsFinite = Annotated[T, Predicate(math.isfinite)]`
|
||||||
|
* `IsNotFinite = Annotated[T, Predicate(Not(math.isfinite))]`
|
||||||
|
* `IsNan = Annotated[T, Predicate(math.isnan)]`
|
||||||
|
* `IsNotNan = Annotated[T, Predicate(Not(math.isnan))]`
|
||||||
|
* `IsInfinite = Annotated[T, Predicate(math.isinf)]`
|
||||||
|
* `IsNotInfinite = Annotated[T, Predicate(Not(math.isinf))]`
|
||||||
|
|
||||||
|
so that you can write e.g. `x: IsFinite[float] = 2.0` instead of the longer
|
||||||
|
(but exactly equivalent) `x: Annotated[float, Predicate(math.isfinite)] = 2.0`.
|
||||||
|
|
||||||
|
Some libraries might have special logic to handle known or understandable predicates,
|
||||||
|
for example by checking for `str.isdigit` and using its presence to both call custom
|
||||||
|
logic to enforce digit-only strings, and customise some generated external schema.
|
||||||
|
Users are therefore encouraged to avoid indirection like `lambda s: s.lower()`, in
|
||||||
|
favor of introspectable methods such as `str.lower` or `re.compile("pattern").search`.
|
||||||
|
|
||||||
|
To enable basic negation of commonly used predicates like `math.isnan` without introducing introspection that makes it impossible for implementers to introspect the predicate we provide a `Not` wrapper that simply negates the predicate in an introspectable manner. Several of the predicates listed above are created in this manner.
|
||||||
|
|
||||||
|
We do not specify what behaviour should be expected for predicates that raise
|
||||||
|
an exception. For example `Annotated[int, Predicate(str.isdigit)]` might silently
|
||||||
|
skip invalid constraints, or statically raise an error; or it might try calling it
|
||||||
|
and then propagate or discard the resulting
|
||||||
|
`TypeError: descriptor 'isdigit' for 'str' objects doesn't apply to a 'int' object`
|
||||||
|
exception. We encourage libraries to document the behaviour they choose.
|
||||||
|
|
||||||
|
### Doc
|
||||||
|
|
||||||
|
`doc()` can be used to add documentation information in `Annotated`, for function and method parameters, variables, class attributes, return types, and any place where `Annotated` can be used.
|
||||||
|
|
||||||
|
It expects a value that can be statically analyzed, as the main use case is for static analysis, editors, documentation generators, and similar tools.
|
||||||
|
|
||||||
|
It returns a `DocInfo` class with a single attribute `documentation` containing the value passed to `doc()`.
|
||||||
|
|
||||||
|
This is the early adopter's alternative form of the [`typing-doc` proposal](https://github.com/tiangolo/fastapi/blob/typing-doc/typing_doc.md).
|
||||||
|
|
||||||
|
### Integrating downstream types with `GroupedMetadata`
|
||||||
|
|
||||||
|
Implementers may choose to provide a convenience wrapper that groups multiple pieces of metadata.
|
||||||
|
This can help reduce verbosity and cognitive overhead for users.
|
||||||
|
For example, an implementer like Pydantic might provide a `Field` or `Meta` type that accepts keyword arguments and transforms these into low-level metadata:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from dataclasses import dataclass
|
||||||
|
from typing import Iterator
|
||||||
|
from annotated_types import GroupedMetadata, Ge
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class Field(GroupedMetadata):
|
||||||
|
ge: int | None = None
|
||||||
|
description: str | None = None
|
||||||
|
|
||||||
|
def __iter__(self) -> Iterator[object]:
|
||||||
|
# Iterating over a GroupedMetadata object should yield annotated-types
|
||||||
|
# constraint metadata objects which describe it as fully as possible,
|
||||||
|
# and may include other unknown objects too.
|
||||||
|
if self.ge is not None:
|
||||||
|
yield Ge(self.ge)
|
||||||
|
if self.description is not None:
|
||||||
|
yield Description(self.description)
|
||||||
|
```
|
||||||
|
|
||||||
|
Libraries consuming annotated-types constraints should check for `GroupedMetadata` and unpack it by iterating over the object and treating the results as if they had been "unpacked" in the `Annotated` type. The same logic should be applied to the [PEP 646 `Unpack` type](https://peps.python.org/pep-0646/), so that `Annotated[T, Field(...)]`, `Annotated[T, Unpack[Field(...)]]` and `Annotated[T, *Field(...)]` are all treated consistently.
|
||||||
|
|
||||||
|
Libraries consuming annotated-types should also ignore any metadata they do not recongize that came from unpacking a `GroupedMetadata`, just like they ignore unrecognized metadata in `Annotated` itself.
|
||||||
|
|
||||||
|
Our own `annotated_types.Interval` class is a `GroupedMetadata` which unpacks itself into `Gt`, `Lt`, etc., so this is not an abstract concern. Similarly, `annotated_types.Len` is a `GroupedMetadata` which unpacks itself into `MinLen` (optionally) and `MaxLen`.
|
||||||
|
|
||||||
|
### Consuming metadata
|
||||||
|
|
||||||
|
We intend to not be prescriptive as to _how_ the metadata and constraints are used, but as an example of how one might parse constraints from types annotations see our [implementation in `test_main.py`](https://github.com/annotated-types/annotated-types/blob/f59cf6d1b5255a0fe359b93896759a180bec30ae/tests/test_main.py#L94-L103).
|
||||||
|
|
||||||
|
It is up to the implementer to determine how this metadata is used.
|
||||||
|
You could use the metadata for runtime type checking, for generating schemas or to generate example data, amongst other use cases.
|
||||||
|
|
||||||
|
## Design & History
|
||||||
|
|
||||||
|
This package was designed at the PyCon 2022 sprints by the maintainers of Pydantic
|
||||||
|
and Hypothesis, with the goal of making it as easy as possible for end-users to
|
||||||
|
provide more informative annotations for use by runtime libraries.
|
||||||
|
|
||||||
|
It is deliberately minimal, and following PEP-593 allows considerable downstream
|
||||||
|
discretion in what (if anything!) they choose to support. Nonetheless, we expect
|
||||||
|
that staying simple and covering _only_ the most common use-cases will give users
|
||||||
|
and maintainers the best experience we can. If you'd like more constraints for your
|
||||||
|
types - follow our lead, by defining them and documenting them downstream!
|
||||||
@@ -0,0 +1,7 @@
|
|||||||
|
annotated_types/__init__.py,sha256=pxBKTUObJ6n3T8C-I2ubobeDHmBEAmgCogWrwSmKm8g,13273
|
||||||
|
annotated_types/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
||||||
|
annotated_types/test_cases.py,sha256=2GdHKstXuBzpf3iXKCjmvFZpyk2zP9Hm9kXGGDhGBo4,6310
|
||||||
|
annotated_types-0.8.0.dist-info/METADATA,sha256=YUmFsnj2Abjvhj-CeDuZHMOtpLifWS63HHxIxfLvIpg,15009
|
||||||
|
annotated_types-0.8.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
|
||||||
|
annotated_types-0.8.0.dist-info/licenses/LICENSE,sha256=_hBJiEsaDZNCkB6I4H8ykl0ksxIdmXK2poBfuYJLCV0,1083
|
||||||
|
annotated_types-0.8.0.dist-info/RECORD,,
|
||||||
@@ -0,0 +1,4 @@
|
|||||||
|
Wheel-Version: 1.0
|
||||||
|
Generator: hatchling 1.31.0
|
||||||
|
Root-Is-Purelib: true
|
||||||
|
Tag: py3-none-any
|
||||||
@@ -0,0 +1,21 @@
|
|||||||
|
The MIT License (MIT)
|
||||||
|
|
||||||
|
Copyright (c) 2022 the contributors
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
@@ -0,0 +1,416 @@
|
|||||||
|
import math
|
||||||
|
import types
|
||||||
|
from collections.abc import Callable, Iterator
|
||||||
|
from dataclasses import dataclass
|
||||||
|
from datetime import tzinfo
|
||||||
|
from types import EllipsisType
|
||||||
|
from typing import (
|
||||||
|
TYPE_CHECKING,
|
||||||
|
Annotated,
|
||||||
|
Any,
|
||||||
|
Literal,
|
||||||
|
Protocol,
|
||||||
|
SupportsFloat,
|
||||||
|
SupportsIndex,
|
||||||
|
TypeVar,
|
||||||
|
Union,
|
||||||
|
runtime_checkable,
|
||||||
|
)
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
'BaseMetadata',
|
||||||
|
'GroupedMetadata',
|
||||||
|
'Gt',
|
||||||
|
'Ge',
|
||||||
|
'Lt',
|
||||||
|
'Le',
|
||||||
|
'Interval',
|
||||||
|
'MultipleOf',
|
||||||
|
'MinLen',
|
||||||
|
'MaxLen',
|
||||||
|
'Len',
|
||||||
|
'Timezone',
|
||||||
|
'Predicate',
|
||||||
|
'LowerCase',
|
||||||
|
'UpperCase',
|
||||||
|
'IsDigits',
|
||||||
|
'IsFinite',
|
||||||
|
'IsNotFinite',
|
||||||
|
'IsNan',
|
||||||
|
'IsNotNan',
|
||||||
|
'IsInfinite',
|
||||||
|
'IsNotInfinite',
|
||||||
|
'doc',
|
||||||
|
'DocInfo',
|
||||||
|
'__version__',
|
||||||
|
)
|
||||||
|
|
||||||
|
__version__ = '0.8.0'
|
||||||
|
|
||||||
|
|
||||||
|
T = TypeVar('T')
|
||||||
|
|
||||||
|
|
||||||
|
# arguments that start with __ are considered
|
||||||
|
# positional only
|
||||||
|
# see https://peps.python.org/pep-0484/#positional-only-arguments
|
||||||
|
|
||||||
|
|
||||||
|
class SupportsGt(Protocol):
|
||||||
|
def __gt__(self: T, __other: T) -> bool:
|
||||||
|
...
|
||||||
|
|
||||||
|
|
||||||
|
class SupportsGe(Protocol):
|
||||||
|
def __ge__(self: T, __other: T) -> bool:
|
||||||
|
...
|
||||||
|
|
||||||
|
|
||||||
|
class SupportsLt(Protocol):
|
||||||
|
def __lt__(self: T, __other: T) -> bool:
|
||||||
|
...
|
||||||
|
|
||||||
|
|
||||||
|
class SupportsLe(Protocol):
|
||||||
|
def __le__(self: T, __other: T) -> bool:
|
||||||
|
...
|
||||||
|
|
||||||
|
|
||||||
|
class SupportsMod(Protocol):
|
||||||
|
def __mod__(self: T, __other: T) -> T:
|
||||||
|
...
|
||||||
|
|
||||||
|
|
||||||
|
class SupportsDiv(Protocol):
|
||||||
|
def __div__(self: T, __other: T) -> T:
|
||||||
|
...
|
||||||
|
|
||||||
|
|
||||||
|
class BaseMetadata:
|
||||||
|
"""Base class for all metadata.
|
||||||
|
|
||||||
|
This exists mainly so that implementers
|
||||||
|
can do `isinstance(..., BaseMetadata)` while traversing field annotations.
|
||||||
|
"""
|
||||||
|
|
||||||
|
__slots__ = ()
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class Gt(BaseMetadata):
|
||||||
|
"""Gt(gt=x) implies that the value must be greater than x.
|
||||||
|
|
||||||
|
It can be used with any type that supports the ``>`` operator,
|
||||||
|
including numbers, dates and times, strings, sets, and so on.
|
||||||
|
"""
|
||||||
|
|
||||||
|
gt: SupportsGt
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class Ge(BaseMetadata):
|
||||||
|
"""Ge(ge=x) implies that the value must be greater than or equal to x.
|
||||||
|
|
||||||
|
It can be used with any type that supports the ``>=`` operator,
|
||||||
|
including numbers, dates and times, strings, sets, and so on.
|
||||||
|
"""
|
||||||
|
|
||||||
|
ge: SupportsGe
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class Lt(BaseMetadata):
|
||||||
|
"""Lt(lt=x) implies that the value must be less than x.
|
||||||
|
|
||||||
|
It can be used with any type that supports the ``<`` operator,
|
||||||
|
including numbers, dates and times, strings, sets, and so on.
|
||||||
|
"""
|
||||||
|
|
||||||
|
lt: SupportsLt
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class Le(BaseMetadata):
|
||||||
|
"""Le(le=x) implies that the value must be less than or equal to x.
|
||||||
|
|
||||||
|
It can be used with any type that supports the ``<=`` operator,
|
||||||
|
including numbers, dates and times, strings, sets, and so on.
|
||||||
|
"""
|
||||||
|
|
||||||
|
le: SupportsLe
|
||||||
|
|
||||||
|
|
||||||
|
@runtime_checkable
|
||||||
|
class GroupedMetadata(Protocol):
|
||||||
|
"""A grouping of multiple objects, like typing.Unpack.
|
||||||
|
|
||||||
|
`GroupedMetadata` on its own is not metadata and has no meaning.
|
||||||
|
All of the constraints and metadata should be fully expressable
|
||||||
|
in terms of the `BaseMetadata`'s returned by `GroupedMetadata.__iter__()`.
|
||||||
|
|
||||||
|
Concrete implementations should override `GroupedMetadata.__iter__()`
|
||||||
|
to add their own metadata.
|
||||||
|
For example:
|
||||||
|
|
||||||
|
>>> @dataclass
|
||||||
|
>>> class Field(GroupedMetadata):
|
||||||
|
>>> gt: float | None = None
|
||||||
|
>>> description: str | None = None
|
||||||
|
...
|
||||||
|
>>> def __iter__(self) -> Iterable[object]:
|
||||||
|
>>> if self.gt is not None:
|
||||||
|
>>> yield Gt(self.gt)
|
||||||
|
>>> if self.description is not None:
|
||||||
|
>>> yield Description(self.gt)
|
||||||
|
|
||||||
|
Also see the implementation of `Interval` below for an example.
|
||||||
|
|
||||||
|
Parsers should recognize this and unpack it so that it can be used
|
||||||
|
both with and without unpacking:
|
||||||
|
|
||||||
|
- `Annotated[int, Field(...)]` (parser must unpack Field)
|
||||||
|
- `Annotated[int, *Field(...)]` (PEP-646)
|
||||||
|
""" # noqa: trailing-whitespace
|
||||||
|
|
||||||
|
@property
|
||||||
|
def __is_annotated_types_grouped_metadata__(self) -> Literal[True]:
|
||||||
|
return True
|
||||||
|
|
||||||
|
def __iter__(self) -> Iterator[object]:
|
||||||
|
...
|
||||||
|
|
||||||
|
if not TYPE_CHECKING:
|
||||||
|
__slots__ = () # allow subclasses to use slots
|
||||||
|
|
||||||
|
def __init_subclass__(cls, *args: Any, **kwargs: Any) -> None:
|
||||||
|
# Basic ABC like functionality without the complexity of an ABC
|
||||||
|
super().__init_subclass__(*args, **kwargs)
|
||||||
|
if cls.__iter__ is GroupedMetadata.__iter__:
|
||||||
|
raise TypeError("Can't subclass GroupedMetadata without implementing __iter__")
|
||||||
|
|
||||||
|
def __iter__(self) -> Iterator[object]: # noqa: F811
|
||||||
|
raise NotImplementedError # more helpful than "None has no attribute..." type errors
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, kw_only=True, slots=True)
|
||||||
|
class Interval(GroupedMetadata):
|
||||||
|
"""Interval can express inclusive or exclusive bounds with a single object.
|
||||||
|
|
||||||
|
It accepts keyword arguments ``gt``, ``ge``, ``lt``, and/or ``le``, which
|
||||||
|
are interpreted the same way as the single-bound constraints.
|
||||||
|
"""
|
||||||
|
|
||||||
|
gt: SupportsGt | None = None
|
||||||
|
ge: SupportsGe | None = None
|
||||||
|
lt: SupportsLt | None = None
|
||||||
|
le: SupportsLe | None = None
|
||||||
|
|
||||||
|
def __iter__(self) -> Iterator[BaseMetadata]:
|
||||||
|
"""Unpack an Interval into zero or more single-bounds."""
|
||||||
|
if self.gt is not None:
|
||||||
|
yield Gt(self.gt)
|
||||||
|
if self.ge is not None:
|
||||||
|
yield Ge(self.ge)
|
||||||
|
if self.lt is not None:
|
||||||
|
yield Lt(self.lt)
|
||||||
|
if self.le is not None:
|
||||||
|
yield Le(self.le)
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class MultipleOf(BaseMetadata):
|
||||||
|
"""MultipleOf(multiple_of=x) might be interpreted in two ways:
|
||||||
|
|
||||||
|
1. Python semantics, implying ``value % multiple_of == 0``, or
|
||||||
|
2. JSONschema semantics, where ``int(value / multiple_of) == value / multiple_of``
|
||||||
|
|
||||||
|
We encourage users to be aware of these two common interpretations,
|
||||||
|
and libraries to carefully document which they implement.
|
||||||
|
"""
|
||||||
|
|
||||||
|
multiple_of: SupportsDiv | SupportsMod
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class MinLen(BaseMetadata):
|
||||||
|
"""
|
||||||
|
MinLen() implies minimum inclusive length,
|
||||||
|
e.g. ``len(value) >= min_length``.
|
||||||
|
"""
|
||||||
|
|
||||||
|
min_length: Annotated[int, Ge(0)]
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class MaxLen(BaseMetadata):
|
||||||
|
"""
|
||||||
|
MaxLen() implies maximum inclusive length,
|
||||||
|
e.g. ``len(value) <= max_length``.
|
||||||
|
"""
|
||||||
|
|
||||||
|
max_length: Annotated[int, Ge(0)]
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class Len(GroupedMetadata):
|
||||||
|
"""
|
||||||
|
Len() implies that ``min_length <= len(value) <= max_length``.
|
||||||
|
|
||||||
|
Upper bound may be omitted or ``None`` to indicate no upper length bound.
|
||||||
|
"""
|
||||||
|
|
||||||
|
min_length: Annotated[int, Ge(0)] = 0
|
||||||
|
max_length: Annotated[int, Ge(0)] | None = None
|
||||||
|
|
||||||
|
def __iter__(self) -> Iterator[BaseMetadata]:
|
||||||
|
"""Unpack a Len into zero or more single-bounds."""
|
||||||
|
if self.min_length > 0:
|
||||||
|
yield MinLen(self.min_length)
|
||||||
|
if self.max_length is not None:
|
||||||
|
yield MaxLen(self.max_length)
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class Timezone(BaseMetadata):
|
||||||
|
"""Timezone(tz=...) requires a datetime to be aware (or ``tz=None``, naive).
|
||||||
|
|
||||||
|
``Annotated[datetime, Timezone(None)]`` must be a naive datetime.
|
||||||
|
``Timezone(...)`` (the ellipsis literal) expresses that the datetime must be
|
||||||
|
tz-aware but any timezone is allowed.
|
||||||
|
|
||||||
|
You may also pass a specific timezone string or tzinfo object such as
|
||||||
|
``Timezone(timezone.utc)`` or ``Timezone("Africa/Abidjan")`` to express that
|
||||||
|
you only allow a specific timezone, though we note that this is often
|
||||||
|
a symptom of poor design.
|
||||||
|
"""
|
||||||
|
|
||||||
|
tz: str | tzinfo | EllipsisType | None
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class Unit(BaseMetadata):
|
||||||
|
"""Indicates that the value is a physical quantity with the specified unit.
|
||||||
|
|
||||||
|
It is intended for usage with numeric types, where the value represents the
|
||||||
|
magnitude of the quantity. For example, ``distance: Annotated[float, Unit('m')]``
|
||||||
|
or ``speed: Annotated[float, Unit('m/s')]``.
|
||||||
|
|
||||||
|
Interpretation of the unit string is left to the discretion of the consumer.
|
||||||
|
It is suggested to follow conventions established by python libraries that work
|
||||||
|
with physical quantities, such as
|
||||||
|
|
||||||
|
- ``pint`` : <https://pint.readthedocs.io/en/stable/>
|
||||||
|
- ``astropy.units``: <https://docs.astropy.org/en/stable/units/>
|
||||||
|
|
||||||
|
For indicating a quantity with a certain dimensionality but without a specific unit
|
||||||
|
it is recommended to use square brackets, e.g. `Annotated[float, Unit('[time]')]`.
|
||||||
|
Note, however, ``annotated_types`` itself makes no use of the unit string.
|
||||||
|
"""
|
||||||
|
|
||||||
|
unit: str
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class Predicate(BaseMetadata):
|
||||||
|
"""``Predicate(func: Callable)`` implies `func(value)` is truthy for valid values.
|
||||||
|
|
||||||
|
Users should prefer statically inspectable metadata, but if you need the full
|
||||||
|
power and flexibility of arbitrary runtime predicates... here it is.
|
||||||
|
|
||||||
|
We provide a few predefined predicates for common string constraints:
|
||||||
|
``LowerCase = Predicate(str.islower)``, ``UpperCase = Predicate(str.isupper)``, and
|
||||||
|
``IsDigits = Predicate(str.isdigit)``. Users are encouraged to use methods which
|
||||||
|
can be given special handling, and avoid indirection like ``lambda s: s.lower()``.
|
||||||
|
|
||||||
|
Some libraries might have special logic to handle certain predicates, e.g. by
|
||||||
|
checking for `str.isdigit` and using its presence to both call custom logic to
|
||||||
|
enforce digit-only strings, and customise some generated external schema.
|
||||||
|
|
||||||
|
We do not specify what behaviour should be expected for predicates that raise
|
||||||
|
an exception. For example `Annotated[int, Predicate(str.isdigit)]` might silently
|
||||||
|
skip invalid constraints, or statically raise an error; or it might try calling it
|
||||||
|
and then propagate or discard the resulting exception.
|
||||||
|
"""
|
||||||
|
|
||||||
|
func: Callable[[Any], bool]
|
||||||
|
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
if getattr(self.func, "__name__", "<lambda>") == "<lambda>":
|
||||||
|
return f"{self.__class__.__name__}({self.func!r})"
|
||||||
|
if isinstance(self.func, (types.MethodType, types.BuiltinMethodType)) and (
|
||||||
|
namespace := getattr(self.func.__self__, "__name__", None)
|
||||||
|
):
|
||||||
|
return f"{self.__class__.__name__}({namespace}.{self.func.__name__})"
|
||||||
|
if isinstance(self.func, type(str.isascii)): # method descriptor
|
||||||
|
return f"{self.__class__.__name__}({self.func.__qualname__})"
|
||||||
|
return f"{self.__class__.__name__}({self.func.__name__})"
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class Not:
|
||||||
|
func: Callable[[Any], bool]
|
||||||
|
|
||||||
|
def __call__(self, __v: Any) -> bool:
|
||||||
|
return not self.func(__v)
|
||||||
|
|
||||||
|
|
||||||
|
_StrType = TypeVar("_StrType", bound=str)
|
||||||
|
|
||||||
|
LowerCase = Annotated[_StrType, Predicate(str.islower)]
|
||||||
|
"""
|
||||||
|
Return True if the string is a lowercase string, False otherwise.
|
||||||
|
|
||||||
|
A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.
|
||||||
|
""" # noqa: E501
|
||||||
|
UpperCase = Annotated[_StrType, Predicate(str.isupper)]
|
||||||
|
"""
|
||||||
|
Return True if the string is an uppercase string, False otherwise.
|
||||||
|
|
||||||
|
A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.
|
||||||
|
""" # noqa: E501
|
||||||
|
IsDigit = Annotated[_StrType, Predicate(str.isdigit)]
|
||||||
|
IsDigits = IsDigit # type: ignore # plural for backwards compatibility, see #63
|
||||||
|
"""
|
||||||
|
Return True if the string is a digit string, False otherwise.
|
||||||
|
|
||||||
|
A string is a digit string if all characters in the string are digits and there is at least one character in the string.
|
||||||
|
""" # noqa: E501
|
||||||
|
IsAscii = Annotated[_StrType, Predicate(str.isascii)]
|
||||||
|
"""
|
||||||
|
Return True if all characters in the string are ASCII, False otherwise.
|
||||||
|
|
||||||
|
ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.
|
||||||
|
"""
|
||||||
|
|
||||||
|
_NumericType = TypeVar('_NumericType', bound=Union[SupportsFloat, SupportsIndex])
|
||||||
|
IsFinite = Annotated[_NumericType, Predicate(math.isfinite)]
|
||||||
|
"""Return True if x is neither an infinity nor a NaN, and False otherwise."""
|
||||||
|
IsNotFinite = Annotated[_NumericType, Predicate(Not(math.isfinite))]
|
||||||
|
"""Return True if x is one of infinity or NaN, and False otherwise"""
|
||||||
|
IsNan = Annotated[_NumericType, Predicate(math.isnan)]
|
||||||
|
"""Return True if x is a NaN (not a number), and False otherwise."""
|
||||||
|
IsNotNan = Annotated[_NumericType, Predicate(Not(math.isnan))]
|
||||||
|
"""Return True if x is anything but NaN (not a number), and False otherwise."""
|
||||||
|
IsInfinite = Annotated[_NumericType, Predicate(math.isinf)]
|
||||||
|
"""Return True if x is a positive or negative infinity, and False otherwise."""
|
||||||
|
IsNotInfinite = Annotated[_NumericType, Predicate(Not(math.isinf))]
|
||||||
|
"""Return True if x is neither a positive or negative infinity, and False otherwise."""
|
||||||
|
|
||||||
|
try:
|
||||||
|
# PEP 727 – Documentation in Annotated Metadata
|
||||||
|
from typing_extensions import Doc # type: ignore[attr-defined]
|
||||||
|
except ImportError:
|
||||||
|
|
||||||
|
@dataclass(frozen=True, slots=True)
|
||||||
|
class Doc: # type: ignore [no-redef]
|
||||||
|
""" "
|
||||||
|
The return value of doc(), mainly to be used by tools that want to extract the
|
||||||
|
Annotated documentation at runtime.
|
||||||
|
"""
|
||||||
|
|
||||||
|
documentation: str
|
||||||
|
"""The documentation string passed to doc()."""
|
||||||
|
|
||||||
|
|
||||||
|
DocInfo = Doc # backwards compatibility
|
||||||
|
doc = Doc
|
||||||
Whitespace-only changes.
@@ -0,0 +1,146 @@
|
|||||||
|
import math
|
||||||
|
from collections.abc import Iterable, Iterator
|
||||||
|
from datetime import date, datetime, timedelta, timezone
|
||||||
|
from decimal import Decimal
|
||||||
|
from typing import Annotated, Any, NamedTuple
|
||||||
|
|
||||||
|
import annotated_types as at
|
||||||
|
|
||||||
|
|
||||||
|
class Case(NamedTuple):
|
||||||
|
"""
|
||||||
|
A test case for `annotated_types`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
annotation: Any
|
||||||
|
valid_cases: Iterable[Any]
|
||||||
|
invalid_cases: Iterable[Any]
|
||||||
|
|
||||||
|
|
||||||
|
def cases() -> Iterable[Case]:
|
||||||
|
# Gt, Ge, Lt, Le
|
||||||
|
yield Case(Annotated[int, at.Gt(4)], (5, 6, 1000), (4, 0, -1))
|
||||||
|
yield Case(Annotated[float, at.Gt(0.5)], (0.6, 0.7, 0.8, 0.9), (0.5, 0.0, -0.1))
|
||||||
|
yield Case(
|
||||||
|
Annotated[datetime, at.Gt(datetime(2000, 1, 1))],
|
||||||
|
[datetime(2000, 1, 2), datetime(2000, 1, 3)],
|
||||||
|
[datetime(2000, 1, 1), datetime(1999, 12, 31)],
|
||||||
|
)
|
||||||
|
yield Case(
|
||||||
|
Annotated[datetime, at.Gt(date(2000, 1, 1))],
|
||||||
|
[date(2000, 1, 2), date(2000, 1, 3)],
|
||||||
|
[date(2000, 1, 1), date(1999, 12, 31)],
|
||||||
|
)
|
||||||
|
yield Case(
|
||||||
|
Annotated[datetime, at.Gt(Decimal('1.123'))],
|
||||||
|
[Decimal('1.1231'), Decimal('123')],
|
||||||
|
[Decimal('1.123'), Decimal('0')],
|
||||||
|
)
|
||||||
|
|
||||||
|
yield Case(Annotated[int, at.Ge(4)], (4, 5, 6, 1000, 4), (0, -1))
|
||||||
|
yield Case(Annotated[float, at.Ge(0.5)], (0.5, 0.6, 0.7, 0.8, 0.9), (0.4, 0.0, -0.1))
|
||||||
|
yield Case(
|
||||||
|
Annotated[datetime, at.Ge(datetime(2000, 1, 1))],
|
||||||
|
[datetime(2000, 1, 2), datetime(2000, 1, 3)],
|
||||||
|
[datetime(1998, 1, 1), datetime(1999, 12, 31)],
|
||||||
|
)
|
||||||
|
|
||||||
|
yield Case(Annotated[int, at.Lt(4)], (0, -1), (4, 5, 6, 1000, 4))
|
||||||
|
yield Case(Annotated[float, at.Lt(0.5)], (0.4, 0.0, -0.1), (0.5, 0.6, 0.7, 0.8, 0.9))
|
||||||
|
yield Case(
|
||||||
|
Annotated[datetime, at.Lt(datetime(2000, 1, 1))],
|
||||||
|
[datetime(1999, 12, 31), datetime(1999, 12, 31)],
|
||||||
|
[datetime(2000, 1, 2), datetime(2000, 1, 3)],
|
||||||
|
)
|
||||||
|
|
||||||
|
yield Case(Annotated[int, at.Le(4)], (4, 0, -1), (5, 6, 1000))
|
||||||
|
yield Case(Annotated[float, at.Le(0.5)], (0.5, 0.0, -0.1), (0.6, 0.7, 0.8, 0.9))
|
||||||
|
yield Case(
|
||||||
|
Annotated[datetime, at.Le(datetime(2000, 1, 1))],
|
||||||
|
[datetime(2000, 1, 1), datetime(1999, 12, 31)],
|
||||||
|
[datetime(2000, 1, 2), datetime(2000, 1, 3)],
|
||||||
|
)
|
||||||
|
|
||||||
|
# Interval
|
||||||
|
yield Case(Annotated[int, at.Interval(gt=4)], (5, 6, 1000), (4, 0, -1))
|
||||||
|
yield Case(Annotated[int, at.Interval(gt=4, lt=10)], (5, 6), (4, 10, 1000, 0, -1))
|
||||||
|
yield Case(Annotated[float, at.Interval(ge=0.5, le=1)], (0.5, 0.9, 1), (0.49, 1.1))
|
||||||
|
yield Case(
|
||||||
|
Annotated[datetime, at.Interval(gt=datetime(2000, 1, 1), le=datetime(2000, 1, 3))],
|
||||||
|
[datetime(2000, 1, 2), datetime(2000, 1, 3)],
|
||||||
|
[datetime(2000, 1, 1), datetime(2000, 1, 4)],
|
||||||
|
)
|
||||||
|
|
||||||
|
yield Case(Annotated[int, at.MultipleOf(multiple_of=3)], (0, 3, 9), (1, 2, 4))
|
||||||
|
yield Case(Annotated[float, at.MultipleOf(multiple_of=0.5)], (0, 0.5, 1, 1.5), (0.4, 1.1))
|
||||||
|
|
||||||
|
# lengths
|
||||||
|
|
||||||
|
yield Case(Annotated[str, at.MinLen(3)], ('123', '1234', 'x' * 10), ('', '1', '12'))
|
||||||
|
yield Case(Annotated[str, at.Len(3)], ('123', '1234', 'x' * 10), ('', '1', '12'))
|
||||||
|
yield Case(Annotated[list[int], at.MinLen(3)], ([1, 2, 3], [1, 2, 3, 4], [1] * 10), ([], [1], [1, 2]))
|
||||||
|
yield Case(Annotated[list[int], at.Len(3)], ([1, 2, 3], [1, 2, 3, 4], [1] * 10), ([], [1], [1, 2]))
|
||||||
|
|
||||||
|
yield Case(Annotated[str, at.MaxLen(4)], ('', '1234'), ('12345', 'x' * 10))
|
||||||
|
yield Case(Annotated[str, at.Len(0, 4)], ('', '1234'), ('12345', 'x' * 10))
|
||||||
|
yield Case(Annotated[list[str], at.MaxLen(4)], ([], ['a', 'bcdef'], ['a', 'b', 'c']), (['a'] * 5, ['b'] * 10))
|
||||||
|
yield Case(Annotated[list[str], at.Len(0, 4)], ([], ['a', 'bcdef'], ['a', 'b', 'c']), (['a'] * 5, ['b'] * 10))
|
||||||
|
|
||||||
|
yield Case(Annotated[str, at.Len(3, 5)], ('123', '12345'), ('', '1', '12', '123456', 'x' * 10))
|
||||||
|
yield Case(Annotated[str, at.Len(3, 3)], ('123',), ('12', '1234'))
|
||||||
|
|
||||||
|
yield Case(Annotated[dict[int, int], at.Len(2, 3)], [{1: 1, 2: 2}], [{}, {1: 1}, {1: 1, 2: 2, 3: 3, 4: 4}])
|
||||||
|
yield Case(Annotated[set[int], at.Len(2, 3)], ({1, 2}, {1, 2, 3}), (set(), {1}, {1, 2, 3, 4}))
|
||||||
|
yield Case(Annotated[tuple[int, ...], at.Len(2, 3)], ((1, 2), (1, 2, 3)), ((), (1,), (1, 2, 3, 4)))
|
||||||
|
|
||||||
|
# Timezone
|
||||||
|
|
||||||
|
yield Case(
|
||||||
|
Annotated[datetime, at.Timezone(None)], [datetime(2000, 1, 1)], [datetime(2000, 1, 1, tzinfo=timezone.utc)]
|
||||||
|
)
|
||||||
|
yield Case(
|
||||||
|
Annotated[datetime, at.Timezone(...)], [datetime(2000, 1, 1, tzinfo=timezone.utc)], [datetime(2000, 1, 1)]
|
||||||
|
)
|
||||||
|
yield Case(
|
||||||
|
Annotated[datetime, at.Timezone(timezone.utc)],
|
||||||
|
[datetime(2000, 1, 1, tzinfo=timezone.utc)],
|
||||||
|
[datetime(2000, 1, 1), datetime(2000, 1, 1, tzinfo=timezone(timedelta(hours=6)))],
|
||||||
|
)
|
||||||
|
yield Case(
|
||||||
|
Annotated[datetime, at.Timezone('Europe/London')],
|
||||||
|
[datetime(2000, 1, 1, tzinfo=timezone(timedelta(0), name='Europe/London'))],
|
||||||
|
[datetime(2000, 1, 1), datetime(2000, 1, 1, tzinfo=timezone(timedelta(hours=6)))],
|
||||||
|
)
|
||||||
|
|
||||||
|
# Quantity
|
||||||
|
|
||||||
|
yield Case(Annotated[float, at.Unit(unit='m')], (5, 4.2), ('5m', '4.2m'))
|
||||||
|
|
||||||
|
# predicate types
|
||||||
|
|
||||||
|
yield Case(at.LowerCase[str], ['abc', 'foobar'], ['', 'A', 'Boom'])
|
||||||
|
yield Case(at.UpperCase[str], ['ABC', 'DEFO'], ['', 'a', 'abc', 'AbC'])
|
||||||
|
yield Case(at.IsDigit[str], ['123'], ['', 'ab', 'a1b2'])
|
||||||
|
yield Case(at.IsAscii[str], ['123', 'foo bar'], ['£100', '😊', 'whatever 👀'])
|
||||||
|
|
||||||
|
yield Case(Annotated[int, at.Predicate(lambda x: x % 2 == 0)], [0, 2, 4], [1, 3, 5])
|
||||||
|
|
||||||
|
yield Case(at.IsFinite[float], [1.23], [math.nan, math.inf, -math.inf])
|
||||||
|
yield Case(at.IsNotFinite[float], [math.nan, math.inf], [1.23])
|
||||||
|
yield Case(at.IsNan[float], [math.nan], [1.23, math.inf])
|
||||||
|
yield Case(at.IsNotNan[float], [1.23, math.inf], [math.nan])
|
||||||
|
yield Case(at.IsInfinite[float], [math.inf], [math.nan, 1.23])
|
||||||
|
yield Case(at.IsNotInfinite[float], [math.nan, 1.23], [math.inf])
|
||||||
|
|
||||||
|
# check stacked predicates
|
||||||
|
yield Case(at.IsInfinite[Annotated[float, at.Predicate(lambda x: x > 0)]], [math.inf], [-math.inf, 1.23, math.nan])
|
||||||
|
|
||||||
|
# doc
|
||||||
|
yield Case(Annotated[int, at.doc("A number")], [1, 2], [])
|
||||||
|
|
||||||
|
# custom GroupedMetadata
|
||||||
|
class MyCustomGroupedMetadata(at.GroupedMetadata):
|
||||||
|
def __iter__(self) -> Iterator[at.Predicate]:
|
||||||
|
yield at.Predicate(lambda x: float(x).is_integer())
|
||||||
|
|
||||||
|
yield Case(Annotated[float, MyCustomGroupedMetadata()], [0, 2.0], [0.01, 1.5])
|
||||||
@@ -0,0 +1,108 @@
|
|||||||
|
Metadata-Version: 2.4
|
||||||
|
Name: anyio
|
||||||
|
Version: 4.15.1
|
||||||
|
Summary: High-level concurrency and networking framework on top of asyncio or Trio
|
||||||
|
Author-email: Alex Grönholm <alex.gronholm@nextday.fi>
|
||||||
|
License-Expression: MIT
|
||||||
|
Project-URL: Documentation, https://anyio.readthedocs.io/en/latest/
|
||||||
|
Project-URL: Changelog, https://anyio.readthedocs.io/en/stable/versionhistory.html
|
||||||
|
Project-URL: Source code, https://github.com/agronholm/anyio
|
||||||
|
Project-URL: Issue tracker, https://github.com/agronholm/anyio/issues
|
||||||
|
Classifier: Development Status :: 5 - Production/Stable
|
||||||
|
Classifier: Intended Audience :: Developers
|
||||||
|
Classifier: Framework :: AnyIO
|
||||||
|
Classifier: Typing :: Typed
|
||||||
|
Classifier: Programming Language :: Python
|
||||||
|
Classifier: Programming Language :: Python :: 3
|
||||||
|
Classifier: Programming Language :: Python :: 3.10
|
||||||
|
Classifier: Programming Language :: Python :: 3.11
|
||||||
|
Classifier: Programming Language :: Python :: 3.12
|
||||||
|
Classifier: Programming Language :: Python :: 3.13
|
||||||
|
Classifier: Programming Language :: Python :: 3.14
|
||||||
|
Classifier: Programming Language :: Python :: 3.15
|
||||||
|
Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
|
||||||
|
Requires-Python: >=3.10
|
||||||
|
Description-Content-Type: text/x-rst
|
||||||
|
License-File: LICENSE
|
||||||
|
Requires-Dist: exceptiongroup>=1.0.2; python_version < "3.11"
|
||||||
|
Requires-Dist: idna>=2.8
|
||||||
|
Requires-Dist: typing_extensions>=4.16.0; python_version < "3.15"
|
||||||
|
Provides-Extra: trio
|
||||||
|
Requires-Dist: trio>=0.32.0; extra == "trio"
|
||||||
|
Dynamic: license-file
|
||||||
|
|
||||||
|
.. image:: https://github.com/agronholm/anyio/actions/workflows/test.yml/badge.svg
|
||||||
|
:target: https://github.com/agronholm/anyio/actions/workflows/test.yml
|
||||||
|
:alt: Build Status
|
||||||
|
.. image:: https://coveralls.io/repos/github/agronholm/anyio/badge.svg?branch=master
|
||||||
|
:target: https://coveralls.io/github/agronholm/anyio?branch=master
|
||||||
|
:alt: Code Coverage
|
||||||
|
.. image:: https://readthedocs.org/projects/anyio/badge/?version=latest
|
||||||
|
:target: https://anyio.readthedocs.io/en/latest/?badge=latest
|
||||||
|
:alt: Documentation
|
||||||
|
.. image:: https://badges.gitter.im/gitterHQ/gitter.svg
|
||||||
|
:target: https://gitter.im/python-trio/AnyIO
|
||||||
|
:alt: Gitter chat
|
||||||
|
.. image:: https://tidelift.com/badges/package/pypi/anyio
|
||||||
|
:target: https://tidelift.com/subscription/pkg/pypi-anyio
|
||||||
|
:alt: Tidelift
|
||||||
|
|
||||||
|
AnyIO is an asynchronous networking and concurrency library that works on top of either asyncio_ or
|
||||||
|
Trio_. It implements Trio-like `structured concurrency`_ (SC) on top of asyncio and works in harmony
|
||||||
|
with the native SC of Trio itself.
|
||||||
|
|
||||||
|
Applications and libraries written against AnyIO's API will run unmodified on either asyncio_ or
|
||||||
|
Trio_. AnyIO can also be adopted into a library or application incrementally – bit by bit, no full
|
||||||
|
refactoring necessary. It will blend in with the native libraries of your chosen backend.
|
||||||
|
|
||||||
|
To find out why you might want to use AnyIO's APIs instead of asyncio's, you can read about it
|
||||||
|
`here <https://anyio.readthedocs.io/en/stable/why.html>`_.
|
||||||
|
|
||||||
|
Documentation
|
||||||
|
-------------
|
||||||
|
|
||||||
|
View full documentation at: https://anyio.readthedocs.io/
|
||||||
|
|
||||||
|
Features
|
||||||
|
--------
|
||||||
|
|
||||||
|
AnyIO offers the following functionality:
|
||||||
|
|
||||||
|
* Task groups (nurseries_ in trio terminology)
|
||||||
|
* High-level networking (TCP, UDP and UNIX sockets)
|
||||||
|
|
||||||
|
* `Happy eyeballs`_ algorithm for TCP connections (more robust than that of asyncio on Python
|
||||||
|
3.8)
|
||||||
|
* async/await style UDP sockets (unlike asyncio where you still have to use Transports and
|
||||||
|
Protocols)
|
||||||
|
|
||||||
|
* A versatile API for byte streams and object streams
|
||||||
|
* Inter-task synchronization and communication (locks, conditions, events, semaphores, object
|
||||||
|
streams and futures)
|
||||||
|
* Worker threads
|
||||||
|
* Subprocesses
|
||||||
|
* Subinterpreter support for code parallelization (on Python 3.13 and later)
|
||||||
|
* Asynchronous file I/O (using worker threads)
|
||||||
|
* Signal handling
|
||||||
|
* Asynchronous versions of the functools_ and itertools_ modules
|
||||||
|
|
||||||
|
AnyIO also comes with its own pytest_ plugin which also supports asynchronous fixtures.
|
||||||
|
It even works with the popular Hypothesis_ library.
|
||||||
|
|
||||||
|
.. _asyncio: https://docs.python.org/3/library/asyncio.html
|
||||||
|
.. _Trio: https://github.com/python-trio/trio
|
||||||
|
.. _structured concurrency: https://en.wikipedia.org/wiki/Structured_concurrency
|
||||||
|
.. _nurseries: https://trio.readthedocs.io/en/stable/reference-core.html#nurseries-and-spawning
|
||||||
|
.. _Happy eyeballs: https://en.wikipedia.org/wiki/Happy_Eyeballs
|
||||||
|
.. _pytest: https://docs.pytest.org/en/latest/
|
||||||
|
.. _functools: https://docs.python.org/3/library/functools.html
|
||||||
|
.. _itertools: https://docs.python.org/3/library/itertools.html
|
||||||
|
.. _Hypothesis: https://hypothesis.works/
|
||||||
|
|
||||||
|
Security contact information
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
To report a security vulnerability, please use the `Tidelift security contact`_.
|
||||||
|
Tidelift will coordinate the fix and disclosure.
|
||||||
|
|
||||||
|
.. _Tidelift security contact: https://tidelift.com/security
|
||||||
@@ -0,0 +1,53 @@
|
|||||||
|
anyio/__init__.py,sha256=OfroYRjIUw_JFj0Zwh1JAaajMQg4VqtoAt0XoOHDRwE,7602
|
||||||
|
anyio/_lazyimport.py,sha256=LCjnYanIfYE9G-Dv_EsqNLDuVRppNicWZjCTfS9-sJU,6082
|
||||||
|
anyio/from_thread.py,sha256=iZZbfcNySi4wAcx1_cxAQE4J0YZC88qRMIYqQ6SF9sc,19415
|
||||||
|
anyio/functools.py,sha256=T4JS8IXq-x1S0Lbo2owF8l9fza2KypO147QLeyz4cjs,11797
|
||||||
|
anyio/itertools.py,sha256=TS7_UCa2Y3cggtaLlWHbjOyf6QhPfQUdPduNW-ddXTE,16255
|
||||||
|
anyio/lowlevel.py,sha256=QyWkvfetbCH0mHkqv1yxGwOaiZ7fyxhpZkHWOXPV5JU,6280
|
||||||
|
anyio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
||||||
|
anyio/pytest_plugin.py,sha256=oLXyOstvRZW3VVbqIODhZsPt4jSz2UGh44YeG2nJXx0,14516
|
||||||
|
anyio/to_interpreter.py,sha256=ATnoT6kei9wDmQZtXTA3SsY4CK7XKr8Ta4_x5i6pbTw,7100
|
||||||
|
anyio/to_process.py,sha256=p6n8j0nreJUl1DEkR_9PL6KRoKtNqFxORTn8qZBvn94,9850
|
||||||
|
anyio/to_thread.py,sha256=8MPVrrQq8ttGvV21cSd68rMto5bhxJ0-i9CupXag5Gs,2750
|
||||||
|
anyio/_backends/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
||||||
|
anyio/_backends/_asyncio.py,sha256=Vqy7O1ymmEpxTiPzehSuBCVTziGALNV-BbsIRaKXsg4,107767
|
||||||
|
anyio/_backends/_trio.py,sha256=Gs8XzX0IeBvje8IEZtJmpNylKCUAChKv7I_YZi3wlmg,45715
|
||||||
|
anyio/_core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
||||||
|
anyio/_core/_asyncio_selector_thread.py,sha256=2PdxFM3cs02Kp6BSppbvmRT7q7asreTW5FgBxEsflBo,5626
|
||||||
|
anyio/_core/_concurrency_utils.py,sha256=kvRXMrnDqgQTBkZc-f279-lBnZM4YbSToXqhnAUCfSc,4522
|
||||||
|
anyio/_core/_contextmanagers.py,sha256=YInBCabiEeS-UaP_Jdxa1CaFC71ETPW8HZTHIM8Rsc8,7215
|
||||||
|
anyio/_core/_eventloop.py,sha256=ByZUeJD9alMfcyTseRo5IzTO0IltEul_Gyq9iqSjqDk,6658
|
||||||
|
anyio/_core/_exceptions.py,sha256=B4ZhLkBQT4tI6vShv4-GJui492IJsoIDTw1FQJEkmAI,5618
|
||||||
|
anyio/_core/_fileio.py,sha256=q--ft9h5Y_FRLzhAnoYrXf3tOuZ8ZyIN2A9mCfMbZRc,34163
|
||||||
|
anyio/_core/_futures.py,sha256=YQq5uhnCnKQMQD62tOLfzEm7dUXY3GQorJdH6ghfgIQ,6177
|
||||||
|
anyio/_core/_resources.py,sha256=Ld5duCe9NwgPfI7EIOh3CMIBYQ7rq6ZQEa7CFS0u9Ec,450
|
||||||
|
anyio/_core/_signals.py,sha256=mjTBB2hTKNPRlU0IhnijeQedpWOGERDiMjSlJQsFrug,1016
|
||||||
|
anyio/_core/_sockets.py,sha256=C8b-3w5H9n0Fo4g7X8WJvk0m6CGh6NVAAFtieBGHK3g,35289
|
||||||
|
anyio/_core/_streams.py,sha256=FczFwIgDpnkK0bODWJXMpsUJYdvAD04kaUaGzJU8DK0,1806
|
||||||
|
anyio/_core/_subprocesses.py,sha256=TMBuGNILz-47w5t9vayJ1GpCpDT6LxsMohJDFCewIRc,7938
|
||||||
|
anyio/_core/_synchronization.py,sha256=ggsd74QPd846faA2HQeT07ONQ5HQ1S78gy8mvB3qCrw,21658
|
||||||
|
anyio/_core/_tasks.py,sha256=J2dhM_Jq3Grsfg_enNWpRz2SxfM15uLt-pEfvoQq3uA,15391
|
||||||
|
anyio/_core/_tempfile.py,sha256=IgoBCFaPhrFvsF9KHcCcrnCRn-UqMfw0WRdSDWgxAiI,19726
|
||||||
|
anyio/_core/_testing.py,sha256=ZRucLh5kqhiFWAJMMbd8yZ6uIvz0rq3WwL72ldosxAU,2340
|
||||||
|
anyio/_core/_typedattr.py,sha256=gt9Dzn-IL0QW14aHPDD8PAtq95FYKNNupHyf37xZGPQ,2607
|
||||||
|
anyio/abc/__init__.py,sha256=XIVvCI2c6oyaOcqXe94k2rzU5_s7-ZNnlxGTk34H4T0,3050
|
||||||
|
anyio/abc/_eventloop.py,sha256=0-UwgB351rkocCt8m3fjTmcNx2Fxn52nUoujG5DzMvU,11127
|
||||||
|
anyio/abc/_resources.py,sha256=hrb0LXUgHSp3i8G6W8JJchdzKXgg1m0T-L7udXmv2y0,900
|
||||||
|
anyio/abc/_sockets.py,sha256=jQWnPX7iDIDyvyvVkbuFhjezw4oI2WggzbW6Vl2-eqs,13162
|
||||||
|
anyio/abc/_streams.py,sha256=IMeOPPutFXRbyeAutxV1HJe7FUQZYp2qKrJJpP1DCv0,7620
|
||||||
|
anyio/abc/_subprocesses.py,sha256=CDqU1p0HuBS0pXUzBW_hbfhihTJRM67n__7qZmoPU84,2123
|
||||||
|
anyio/abc/_tasks.py,sha256=HBPpT72aOy0bwMAxBCKmnXsR328wCYRjYm3iaVw2fQo,7070
|
||||||
|
anyio/abc/_testing.py,sha256=A9Y8RAClIPn1A0aNHBN8YoaRy_MKOpbFGEbTHAXgB6U,2145
|
||||||
|
anyio/streams/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
||||||
|
anyio/streams/buffered.py,sha256=u7hCD8SNrYHcutG6K5wEiy1F88-pizgjvEFM22Kq2Cw,6746
|
||||||
|
anyio/streams/file.py,sha256=6jujI2m-QJITqqKFamrupX_DNsU7y2Fz3omLZxOLuY0,4524
|
||||||
|
anyio/streams/memory.py,sha256=rpxNzDMag9PCOynBqN64KyuAfAPB41vFyRP-Npo-lE0,10793
|
||||||
|
anyio/streams/stapled.py,sha256=UJ2Rgt0NUmM1VovRNOoZoic960lcbDjb3vhfZg3b_Z0,4845
|
||||||
|
anyio/streams/text.py,sha256=BcVAGJw1VRvtIqnv-o0Rb0pwH7p8vwlvl21xHq522ag,5765
|
||||||
|
anyio/streams/tls.py,sha256=fqLmxvULFO9rvxGyJ33VPrOIN7E3eiU1q90BkmKigQ8,15818
|
||||||
|
anyio-4.15.1.dist-info/licenses/LICENSE,sha256=U2GsncWPLvX9LpsJxoKXwX8ElQkJu8gCO9uC6s8iwrA,1081
|
||||||
|
anyio-4.15.1.dist-info/METADATA,sha256=BDrstXGvcYnopsUo9djjJUXxss36r3YdUebVtn6jyoE,4733
|
||||||
|
anyio-4.15.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
|
||||||
|
anyio-4.15.1.dist-info/entry_points.txt,sha256=_d6Yu6uiaZmNe0CydowirE9Cmg7zUL2g08tQpoS3Qvc,39
|
||||||
|
anyio-4.15.1.dist-info/top_level.txt,sha256=QglSMiWX8_5dpoVAEIHdEYzvqFMdSYWmCj6tYw2ITkQ,6
|
||||||
|
anyio-4.15.1.dist-info/RECORD,,
|
||||||
@@ -0,0 +1,5 @@
|
|||||||
|
Wheel-Version: 1.0
|
||||||
|
Generator: setuptools (84.0.0)
|
||||||
|
Root-Is-Purelib: true
|
||||||
|
Tag: py3-none-any
|
||||||
|
|
||||||
@@ -0,0 +1,2 @@
|
|||||||
|
[pytest11]
|
||||||
|
anyio = anyio.pytest_plugin
|
||||||
@@ -0,0 +1,20 @@
|
|||||||
|
The MIT License (MIT)
|
||||||
|
|
||||||
|
Copyright (c) 2018 Alex Grönholm
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
||||||
|
this software and associated documentation files (the "Software"), to deal in
|
||||||
|
the Software without restriction, including without limitation the rights to
|
||||||
|
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
||||||
|
the Software, and to permit persons to whom the Software is furnished to do so,
|
||||||
|
subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
||||||
|
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
||||||
|
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
||||||
|
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
||||||
|
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
anyio
|
||||||
@@ -0,0 +1,154 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from typing import TYPE_CHECKING
|
||||||
|
|
||||||
|
from ._lazyimport import (
|
||||||
|
fix_package_names,
|
||||||
|
install_lazy_importer,
|
||||||
|
set_deprecated_aliases,
|
||||||
|
)
|
||||||
|
|
||||||
|
if TYPE_CHECKING or not install_lazy_importer():
|
||||||
|
from ._core._concurrency_utils import amap as amap
|
||||||
|
from ._core._concurrency_utils import as_completed as as_completed
|
||||||
|
from ._core._concurrency_utils import gather as gather
|
||||||
|
from ._core._contextmanagers import (
|
||||||
|
AsyncContextManagerMixin as AsyncContextManagerMixin,
|
||||||
|
)
|
||||||
|
from ._core._contextmanagers import ContextManagerMixin as ContextManagerMixin
|
||||||
|
from ._core._eventloop import current_time as current_time
|
||||||
|
from ._core._eventloop import get_all_backends as get_all_backends
|
||||||
|
from ._core._eventloop import get_available_backends as get_available_backends
|
||||||
|
from ._core._eventloop import get_cancelled_exc_class as get_cancelled_exc_class
|
||||||
|
from ._core._eventloop import run as run
|
||||||
|
from ._core._eventloop import sleep as sleep
|
||||||
|
from ._core._eventloop import sleep_forever as sleep_forever
|
||||||
|
from ._core._eventloop import sleep_until as sleep_until
|
||||||
|
from ._core._exceptions import BrokenResourceError as BrokenResourceError
|
||||||
|
from ._core._exceptions import BrokenWorkerInterpreter as BrokenWorkerInterpreter
|
||||||
|
from ._core._exceptions import BrokenWorkerProcess as BrokenWorkerProcess
|
||||||
|
from ._core._exceptions import BusyResourceError as BusyResourceError
|
||||||
|
from ._core._exceptions import ClosedResourceError as ClosedResourceError
|
||||||
|
from ._core._exceptions import ConnectionFailed as ConnectionFailed
|
||||||
|
from ._core._exceptions import DelimiterNotFound as DelimiterNotFound
|
||||||
|
from ._core._exceptions import EndOfStream as EndOfStream
|
||||||
|
from ._core._exceptions import FutureAlreadyFinished as FutureAlreadyFinished
|
||||||
|
from ._core._exceptions import FutureCancelled as FutureCancelled
|
||||||
|
from ._core._exceptions import FutureFailed as FutureFailed
|
||||||
|
from ._core._exceptions import FutureNotFinished as FutureNotFinished
|
||||||
|
from ._core._exceptions import IncompleteRead as IncompleteRead
|
||||||
|
from ._core._exceptions import NoEventLoopError as NoEventLoopError
|
||||||
|
from ._core._exceptions import RunFinishedError as RunFinishedError
|
||||||
|
from ._core._exceptions import TaskCancelled as TaskCancelled
|
||||||
|
from ._core._exceptions import TaskFailed as TaskFailed
|
||||||
|
from ._core._exceptions import TaskNotFinished as TaskNotFinished
|
||||||
|
from ._core._exceptions import (
|
||||||
|
TypedAttributeLookupError as TypedAttributeLookupError,
|
||||||
|
)
|
||||||
|
from ._core._exceptions import WouldBlock as WouldBlock
|
||||||
|
from ._core._fileio import AsyncFile as AsyncFile
|
||||||
|
from ._core._fileio import Path as Path
|
||||||
|
from ._core._fileio import open_file as open_file
|
||||||
|
from ._core._fileio import wrap_file as wrap_file
|
||||||
|
from ._core._futures import Future as Future
|
||||||
|
from ._core._resources import aclose_forcefully as aclose_forcefully
|
||||||
|
from ._core._signals import open_signal_receiver as open_signal_receiver
|
||||||
|
from ._core._sockets import TCPConnectable as TCPConnectable
|
||||||
|
from ._core._sockets import UNIXConnectable as UNIXConnectable
|
||||||
|
from ._core._sockets import as_connectable as as_connectable
|
||||||
|
from ._core._sockets import connect_tcp as connect_tcp
|
||||||
|
from ._core._sockets import connect_unix as connect_unix
|
||||||
|
from ._core._sockets import (
|
||||||
|
create_connected_udp_socket as create_connected_udp_socket,
|
||||||
|
)
|
||||||
|
from ._core._sockets import (
|
||||||
|
create_connected_unix_datagram_socket as create_connected_unix_datagram_socket,
|
||||||
|
)
|
||||||
|
from ._core._sockets import create_tcp_listener as create_tcp_listener
|
||||||
|
from ._core._sockets import create_udp_socket as create_udp_socket
|
||||||
|
from ._core._sockets import (
|
||||||
|
create_unix_datagram_socket as create_unix_datagram_socket,
|
||||||
|
)
|
||||||
|
from ._core._sockets import create_unix_listener as create_unix_listener
|
||||||
|
from ._core._sockets import getaddrinfo as getaddrinfo
|
||||||
|
from ._core._sockets import getnameinfo as getnameinfo
|
||||||
|
from ._core._sockets import notify_closing as notify_closing
|
||||||
|
from ._core._sockets import wait_readable as wait_readable
|
||||||
|
from ._core._sockets import wait_socket_readable as wait_socket_readable
|
||||||
|
from ._core._sockets import wait_socket_writable as wait_socket_writable
|
||||||
|
from ._core._sockets import wait_writable as wait_writable
|
||||||
|
from ._core._streams import (
|
||||||
|
create_memory_object_stream as create_memory_object_stream,
|
||||||
|
)
|
||||||
|
from ._core._subprocesses import open_process as open_process
|
||||||
|
from ._core._subprocesses import run_process as run_process
|
||||||
|
from ._core._synchronization import CapacityLimiter as CapacityLimiter
|
||||||
|
from ._core._synchronization import (
|
||||||
|
CapacityLimiterStatistics as CapacityLimiterStatistics,
|
||||||
|
)
|
||||||
|
from ._core._synchronization import Condition as Condition
|
||||||
|
from ._core._synchronization import ConditionStatistics as ConditionStatistics
|
||||||
|
from ._core._synchronization import Event as Event
|
||||||
|
from ._core._synchronization import EventStatistics as EventStatistics
|
||||||
|
from ._core._synchronization import Lock as Lock
|
||||||
|
from ._core._synchronization import LockStatistics as LockStatistics
|
||||||
|
from ._core._synchronization import ResourceGuard as ResourceGuard
|
||||||
|
from ._core._synchronization import Semaphore as Semaphore
|
||||||
|
from ._core._synchronization import SemaphoreStatistics as SemaphoreStatistics
|
||||||
|
from ._core._tasks import TASK_STATUS_IGNORED as TASK_STATUS_IGNORED
|
||||||
|
from ._core._tasks import CancelScope as CancelScope
|
||||||
|
from ._core._tasks import TaskHandle as TaskHandle
|
||||||
|
from ._core._tasks import create_task_group as create_task_group
|
||||||
|
from ._core._tasks import current_effective_deadline as current_effective_deadline
|
||||||
|
from ._core._tasks import fail_after as fail_after
|
||||||
|
from ._core._tasks import fail_at as fail_at
|
||||||
|
from ._core._tasks import move_on_after as move_on_after
|
||||||
|
from ._core._tasks import move_on_at as move_on_at
|
||||||
|
from ._core._tempfile import NamedTemporaryFile as NamedTemporaryFile
|
||||||
|
from ._core._tempfile import SpooledTemporaryFile as SpooledTemporaryFile
|
||||||
|
from ._core._tempfile import TemporaryDirectory as TemporaryDirectory
|
||||||
|
from ._core._tempfile import TemporaryFile as TemporaryFile
|
||||||
|
from ._core._tempfile import gettempdir as gettempdir
|
||||||
|
from ._core._tempfile import gettempdirb as gettempdirb
|
||||||
|
from ._core._tempfile import mkdtemp as mkdtemp
|
||||||
|
from ._core._tempfile import mkstemp as mkstemp
|
||||||
|
from ._core._testing import TaskInfo as TaskInfo
|
||||||
|
from ._core._testing import get_current_task as get_current_task
|
||||||
|
from ._core._testing import get_running_tasks as get_running_tasks
|
||||||
|
from ._core._testing import wait_all_tasks_blocked as wait_all_tasks_blocked
|
||||||
|
from ._core._typedattr import TypedAttributeProvider as TypedAttributeProvider
|
||||||
|
from ._core._typedattr import TypedAttributeSet as TypedAttributeSet
|
||||||
|
from ._core._typedattr import typed_attribute as typed_attribute
|
||||||
|
|
||||||
|
# ruff: isort: off
|
||||||
|
from . import (
|
||||||
|
abc as abc,
|
||||||
|
)
|
||||||
|
from . import (
|
||||||
|
from_thread as from_thread,
|
||||||
|
)
|
||||||
|
from . import (
|
||||||
|
functools as functools,
|
||||||
|
)
|
||||||
|
from . import (
|
||||||
|
itertools as itertools,
|
||||||
|
)
|
||||||
|
from . import (
|
||||||
|
lowlevel as lowlevel,
|
||||||
|
)
|
||||||
|
from . import (
|
||||||
|
to_interpreter as to_interpreter,
|
||||||
|
)
|
||||||
|
from . import (
|
||||||
|
to_process as to_process,
|
||||||
|
)
|
||||||
|
from . import (
|
||||||
|
to_thread as to_thread,
|
||||||
|
)
|
||||||
|
|
||||||
|
fix_package_names()
|
||||||
|
set_deprecated_aliases(
|
||||||
|
{
|
||||||
|
"BrokenWorkerIntepreter": "anyio.BrokenWorkerInterpreter",
|
||||||
|
}
|
||||||
|
)
|
||||||
Whitespace-only changes.
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
Whitespace-only changes.
@@ -0,0 +1,167 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import asyncio
|
||||||
|
import socket
|
||||||
|
import threading
|
||||||
|
from collections.abc import Callable
|
||||||
|
from selectors import EVENT_READ, EVENT_WRITE, DefaultSelector
|
||||||
|
from typing import TYPE_CHECKING, Any
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
from _typeshed import FileDescriptorLike
|
||||||
|
|
||||||
|
_selector_lock = threading.Lock()
|
||||||
|
_selector: Selector | None = None
|
||||||
|
|
||||||
|
|
||||||
|
class Selector:
|
||||||
|
def __init__(self) -> None:
|
||||||
|
self._thread = threading.Thread(target=self.run, name="AnyIO socket selector")
|
||||||
|
self._selector = DefaultSelector()
|
||||||
|
self._send, self._receive = socket.socketpair()
|
||||||
|
self._send.setblocking(False)
|
||||||
|
self._receive.setblocking(False)
|
||||||
|
# This somewhat reduces the amount of memory wasted queueing up data
|
||||||
|
# for wakeups. With these settings, maximum number of 1-byte sends
|
||||||
|
# before getting BlockingIOError:
|
||||||
|
# Linux 4.8: 6
|
||||||
|
# macOS (darwin 15.5): 1
|
||||||
|
# Windows 10: 525347
|
||||||
|
# Windows you're weird. (And on Windows setting SNDBUF to 0 makes send
|
||||||
|
# blocking, even on non-blocking sockets, so don't do that.)
|
||||||
|
self._receive.setsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF, 1)
|
||||||
|
self._send.setsockopt(socket.SOL_SOCKET, socket.SO_SNDBUF, 1)
|
||||||
|
# On Windows this is a TCP socket so this might matter. On other
|
||||||
|
# platforms this fails b/c AF_UNIX sockets aren't actually TCP.
|
||||||
|
try:
|
||||||
|
self._send.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
|
||||||
|
except OSError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
self._selector.register(self._receive, EVENT_READ)
|
||||||
|
self._closed = False
|
||||||
|
|
||||||
|
def start(self) -> None:
|
||||||
|
self._thread.start()
|
||||||
|
threading._register_atexit(self._stop) # type: ignore[attr-defined]
|
||||||
|
|
||||||
|
def _stop(self) -> None:
|
||||||
|
global _selector
|
||||||
|
self._closed = True
|
||||||
|
self._notify_self()
|
||||||
|
self._send.close()
|
||||||
|
self._thread.join()
|
||||||
|
self._selector.unregister(self._receive)
|
||||||
|
self._receive.close()
|
||||||
|
self._selector.close()
|
||||||
|
_selector = None
|
||||||
|
assert not self._selector.get_map(), (
|
||||||
|
"selector still has registered file descriptors after shutdown"
|
||||||
|
)
|
||||||
|
|
||||||
|
def _notify_self(self) -> None:
|
||||||
|
try:
|
||||||
|
self._send.send(b"\x00")
|
||||||
|
except BlockingIOError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
def add_reader(self, fd: FileDescriptorLike, callback: Callable[[], Any]) -> None:
|
||||||
|
loop = asyncio.get_running_loop()
|
||||||
|
try:
|
||||||
|
key = self._selector.get_key(fd)
|
||||||
|
except KeyError:
|
||||||
|
self._selector.register(fd, EVENT_READ, {EVENT_READ: (loop, callback)})
|
||||||
|
else:
|
||||||
|
if EVENT_READ in key.data:
|
||||||
|
raise ValueError(
|
||||||
|
"this file descriptor is already registered for reading"
|
||||||
|
)
|
||||||
|
|
||||||
|
key.data[EVENT_READ] = loop, callback
|
||||||
|
self._selector.modify(fd, key.events | EVENT_READ, key.data)
|
||||||
|
|
||||||
|
self._notify_self()
|
||||||
|
|
||||||
|
def add_writer(self, fd: FileDescriptorLike, callback: Callable[[], Any]) -> None:
|
||||||
|
loop = asyncio.get_running_loop()
|
||||||
|
try:
|
||||||
|
key = self._selector.get_key(fd)
|
||||||
|
except KeyError:
|
||||||
|
self._selector.register(fd, EVENT_WRITE, {EVENT_WRITE: (loop, callback)})
|
||||||
|
else:
|
||||||
|
if EVENT_WRITE in key.data:
|
||||||
|
raise ValueError(
|
||||||
|
"this file descriptor is already registered for writing"
|
||||||
|
)
|
||||||
|
|
||||||
|
key.data[EVENT_WRITE] = loop, callback
|
||||||
|
self._selector.modify(fd, key.events | EVENT_WRITE, key.data)
|
||||||
|
|
||||||
|
self._notify_self()
|
||||||
|
|
||||||
|
def remove_reader(self, fd: FileDescriptorLike) -> bool:
|
||||||
|
try:
|
||||||
|
key = self._selector.get_key(fd)
|
||||||
|
except KeyError:
|
||||||
|
return False
|
||||||
|
|
||||||
|
if new_events := key.events ^ EVENT_READ:
|
||||||
|
del key.data[EVENT_READ]
|
||||||
|
self._selector.modify(fd, new_events, key.data)
|
||||||
|
else:
|
||||||
|
self._selector.unregister(fd)
|
||||||
|
|
||||||
|
return True
|
||||||
|
|
||||||
|
def remove_writer(self, fd: FileDescriptorLike) -> bool:
|
||||||
|
try:
|
||||||
|
key = self._selector.get_key(fd)
|
||||||
|
except KeyError:
|
||||||
|
return False
|
||||||
|
|
||||||
|
if new_events := key.events ^ EVENT_WRITE:
|
||||||
|
del key.data[EVENT_WRITE]
|
||||||
|
self._selector.modify(fd, new_events, key.data)
|
||||||
|
else:
|
||||||
|
self._selector.unregister(fd)
|
||||||
|
|
||||||
|
return True
|
||||||
|
|
||||||
|
def run(self) -> None:
|
||||||
|
while not self._closed:
|
||||||
|
for key, events in self._selector.select():
|
||||||
|
if key.fileobj is self._receive:
|
||||||
|
try:
|
||||||
|
while self._receive.recv(4096):
|
||||||
|
pass
|
||||||
|
except BlockingIOError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
continue
|
||||||
|
|
||||||
|
if events & EVENT_READ:
|
||||||
|
loop, callback = key.data[EVENT_READ]
|
||||||
|
self.remove_reader(key.fd)
|
||||||
|
try:
|
||||||
|
loop.call_soon_threadsafe(callback)
|
||||||
|
except RuntimeError:
|
||||||
|
pass # the loop was already closed
|
||||||
|
|
||||||
|
if events & EVENT_WRITE:
|
||||||
|
loop, callback = key.data[EVENT_WRITE]
|
||||||
|
self.remove_writer(key.fd)
|
||||||
|
try:
|
||||||
|
loop.call_soon_threadsafe(callback)
|
||||||
|
except RuntimeError:
|
||||||
|
pass # the loop was already closed
|
||||||
|
|
||||||
|
|
||||||
|
def get_selector() -> Selector:
|
||||||
|
global _selector
|
||||||
|
|
||||||
|
with _selector_lock:
|
||||||
|
if _selector is None:
|
||||||
|
_selector = Selector()
|
||||||
|
_selector.start()
|
||||||
|
|
||||||
|
return _selector
|
||||||
@@ -0,0 +1,156 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from inspect import iscoroutine
|
||||||
|
|
||||||
|
__all__ = ("amap", "as_completed", "gather")
|
||||||
|
|
||||||
|
from collections.abc import AsyncGenerator, Awaitable, Callable, Coroutine, Iterable
|
||||||
|
from contextlib import asynccontextmanager
|
||||||
|
from typing import TYPE_CHECKING, Any, TypeVar, overload
|
||||||
|
|
||||||
|
from ..abc._tasks import get_coro_name
|
||||||
|
from ._exceptions import BrokenResourceError
|
||||||
|
from ._streams import create_memory_object_stream
|
||||||
|
from ._tasks import TaskHandle, create_task_group
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
|
||||||
|
|
||||||
|
R = TypeVar("R")
|
||||||
|
S = TypeVar("S")
|
||||||
|
T = TypeVar("T")
|
||||||
|
U = TypeVar("U")
|
||||||
|
V = TypeVar("V")
|
||||||
|
W = TypeVar("W")
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def gather(
|
||||||
|
coro1: Coroutine[Any, Any, R], coro2: Coroutine[Any, Any, S], /
|
||||||
|
) -> tuple[R, S]: ...
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def gather(
|
||||||
|
coro1: Coroutine[Any, Any, R],
|
||||||
|
coro2: Coroutine[Any, Any, S],
|
||||||
|
coro3: Coroutine[Any, Any, T],
|
||||||
|
/,
|
||||||
|
) -> tuple[R, S, T]: ...
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def gather(
|
||||||
|
coro1: Coroutine[Any, Any, R],
|
||||||
|
coro2: Coroutine[Any, Any, S],
|
||||||
|
coro3: Coroutine[Any, Any, T],
|
||||||
|
coro4: Coroutine[Any, Any, U],
|
||||||
|
/,
|
||||||
|
) -> tuple[R, S, T, U]: ...
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def gather(
|
||||||
|
coro1: Coroutine[Any, Any, R],
|
||||||
|
coro2: Coroutine[Any, Any, S],
|
||||||
|
coro3: Coroutine[Any, Any, T],
|
||||||
|
coro4: Coroutine[Any, Any, U],
|
||||||
|
coro5: Coroutine[Any, Any, V],
|
||||||
|
/,
|
||||||
|
) -> tuple[R, S, T, U, V]: ...
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def gather(
|
||||||
|
coro1: Coroutine[Any, Any, R],
|
||||||
|
coro2: Coroutine[Any, Any, S],
|
||||||
|
coro3: Coroutine[Any, Any, T],
|
||||||
|
coro4: Coroutine[Any, Any, U],
|
||||||
|
coro5: Coroutine[Any, Any, V],
|
||||||
|
coro6: Coroutine[Any, Any, W],
|
||||||
|
/,
|
||||||
|
) -> tuple[R, S, T, U, V, W]: ...
|
||||||
|
|
||||||
|
|
||||||
|
# handle arbitrary length if awaitables are all of the same type
|
||||||
|
@overload
|
||||||
|
async def gather(*coros: Coroutine[Any, Any, R]) -> tuple[R, ...]: ...
|
||||||
|
|
||||||
|
|
||||||
|
async def gather(*coros: Coroutine[Any, Any, Any]) -> tuple[Any, ...]:
|
||||||
|
"""
|
||||||
|
Run coroutines concurrently in a task group. The order of result values corresponds
|
||||||
|
to the order of coroutines passed.
|
||||||
|
|
||||||
|
:param coros: coroutine objects to run as tasks
|
||||||
|
:return: task results for each argument in the same order as they were passed
|
||||||
|
|
||||||
|
"""
|
||||||
|
handles: list[TaskHandle[Any]] = []
|
||||||
|
async with create_task_group() as tg:
|
||||||
|
handles.extend(tg.create_task(coro) for coro in coros)
|
||||||
|
|
||||||
|
return tuple(h.return_value for h in handles)
|
||||||
|
|
||||||
|
|
||||||
|
@asynccontextmanager
|
||||||
|
async def as_completed(
|
||||||
|
*awaitables: Awaitable[R],
|
||||||
|
) -> AsyncGenerator[MemoryObjectReceiveStream[TaskHandle[R]]]:
|
||||||
|
"""
|
||||||
|
Run awaitable objects concurrently in a task group, returning an iterator which can
|
||||||
|
be used to get finished task handles in the order they complete.
|
||||||
|
|
||||||
|
:param awaitables: awaitable objects to run as tasks
|
||||||
|
:return: MemoryObjectReceiveStream for iterating over task handles as tasks complete.
|
||||||
|
|
||||||
|
"""
|
||||||
|
if not awaitables:
|
||||||
|
raise ValueError("as_completed() takes at least one awaitable")
|
||||||
|
|
||||||
|
send, recv = create_memory_object_stream[TaskHandle[R]](len(awaitables))
|
||||||
|
task_handles: list[TaskHandle[R]] = []
|
||||||
|
|
||||||
|
async def runner(
|
||||||
|
awaitable: Awaitable[R],
|
||||||
|
index: int,
|
||||||
|
_send: MemoryObjectSendStream[TaskHandle[R]],
|
||||||
|
) -> R:
|
||||||
|
async with _send:
|
||||||
|
try:
|
||||||
|
return await awaitable
|
||||||
|
finally:
|
||||||
|
try:
|
||||||
|
_send.send_nowait(task_handles[index])
|
||||||
|
except BrokenResourceError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
async with recv, create_task_group() as tg:
|
||||||
|
async with send:
|
||||||
|
for i, awaitable in enumerate(awaitables):
|
||||||
|
name = get_coro_name(awaitable) if iscoroutine(awaitable) else None
|
||||||
|
task_handles.append(
|
||||||
|
tg.start_soon(runner, awaitable, i, send.clone(), name=name)
|
||||||
|
)
|
||||||
|
try:
|
||||||
|
yield recv
|
||||||
|
finally:
|
||||||
|
tg.cancel_scope.cancel()
|
||||||
|
|
||||||
|
|
||||||
|
async def amap(
|
||||||
|
func: Callable[[T], Coroutine[Any, Any, R]], args: Iterable[T]
|
||||||
|
) -> list[R]:
|
||||||
|
"""
|
||||||
|
Run the given coroutine function concurrently for multiple argument values.
|
||||||
|
|
||||||
|
:param func: a coroutine function that takes a single argument
|
||||||
|
:param args: a sequence of argument values to pass to ``func``
|
||||||
|
:return: task results for each argument in the same order as they were passed
|
||||||
|
|
||||||
|
"""
|
||||||
|
handles: list[TaskHandle[R]] = []
|
||||||
|
async with create_task_group() as tg:
|
||||||
|
handles.extend(tg.start_soon(func, arg) for arg in args)
|
||||||
|
|
||||||
|
return [h.return_value for h in handles]
|
||||||
@@ -0,0 +1,200 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from abc import abstractmethod
|
||||||
|
from contextlib import AbstractAsyncContextManager, AbstractContextManager
|
||||||
|
from inspect import isasyncgen, iscoroutine, isgenerator
|
||||||
|
from types import TracebackType
|
||||||
|
from typing import Protocol, TypeVar, cast, final
|
||||||
|
|
||||||
|
_T_co = TypeVar("_T_co", covariant=True)
|
||||||
|
_ExitT_co = TypeVar("_ExitT_co", covariant=True, bound="bool | None")
|
||||||
|
|
||||||
|
|
||||||
|
class _SupportsCtxMgr(Protocol[_T_co, _ExitT_co]):
|
||||||
|
def __contextmanager__(self) -> AbstractContextManager[_T_co, _ExitT_co]: ...
|
||||||
|
|
||||||
|
|
||||||
|
class _SupportsAsyncCtxMgr(Protocol[_T_co, _ExitT_co]):
|
||||||
|
def __asynccontextmanager__(
|
||||||
|
self,
|
||||||
|
) -> AbstractAsyncContextManager[_T_co, _ExitT_co]: ...
|
||||||
|
|
||||||
|
|
||||||
|
class ContextManagerMixin:
|
||||||
|
"""
|
||||||
|
Mixin class providing context manager functionality via a generator-based
|
||||||
|
implementation.
|
||||||
|
|
||||||
|
This class allows you to implement a context manager via :meth:`__contextmanager__`
|
||||||
|
which should return a generator. The mechanics are meant to mirror those of
|
||||||
|
:func:`@contextmanager <contextlib.contextmanager>`.
|
||||||
|
|
||||||
|
.. note:: Classes using this mix-in are not reentrant as context managers, meaning
|
||||||
|
that once you enter it, you can't re-enter before first exiting it.
|
||||||
|
|
||||||
|
.. seealso:: :doc:`contextmanagers`
|
||||||
|
"""
|
||||||
|
|
||||||
|
__cm: AbstractContextManager[object, bool | None] | None = None
|
||||||
|
|
||||||
|
@final
|
||||||
|
def __enter__(self: _SupportsCtxMgr[_T_co, bool | None]) -> _T_co:
|
||||||
|
# Needed for mypy to assume self still has the __cm member
|
||||||
|
assert isinstance(self, ContextManagerMixin)
|
||||||
|
if self.__cm is not None:
|
||||||
|
raise RuntimeError(
|
||||||
|
f"this {self.__class__.__qualname__} has already been entered"
|
||||||
|
)
|
||||||
|
|
||||||
|
cm = self.__contextmanager__()
|
||||||
|
if not isinstance(cm, AbstractContextManager):
|
||||||
|
if isgenerator(cm):
|
||||||
|
raise TypeError(
|
||||||
|
"__contextmanager__() returned a generator object instead of "
|
||||||
|
"a context manager. Did you forget to add the @contextmanager "
|
||||||
|
"decorator?"
|
||||||
|
)
|
||||||
|
|
||||||
|
raise TypeError(
|
||||||
|
f"__contextmanager__() did not return a context manager object, "
|
||||||
|
f"but {cm.__class__!r}"
|
||||||
|
)
|
||||||
|
|
||||||
|
if cm is self:
|
||||||
|
raise TypeError(
|
||||||
|
f"{self.__class__.__qualname__}.__contextmanager__() returned "
|
||||||
|
f"self. Did you forget to add the @contextmanager decorator and a "
|
||||||
|
f"'yield' statement?"
|
||||||
|
)
|
||||||
|
|
||||||
|
value = cm.__enter__()
|
||||||
|
self.__cm = cm
|
||||||
|
return value
|
||||||
|
|
||||||
|
@final
|
||||||
|
def __exit__(
|
||||||
|
self: _SupportsCtxMgr[object, _ExitT_co],
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> _ExitT_co:
|
||||||
|
# Needed for mypy to assume self still has the __cm member
|
||||||
|
assert isinstance(self, ContextManagerMixin)
|
||||||
|
if self.__cm is None:
|
||||||
|
raise RuntimeError(
|
||||||
|
f"this {self.__class__.__qualname__} has not been entered yet"
|
||||||
|
)
|
||||||
|
|
||||||
|
# Prevent circular references
|
||||||
|
cm = self.__cm
|
||||||
|
del self.__cm
|
||||||
|
|
||||||
|
return cast(_ExitT_co, cm.__exit__(exc_type, exc_val, exc_tb))
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
def __contextmanager__(self) -> AbstractContextManager[object, bool | None]:
|
||||||
|
"""
|
||||||
|
Implement your context manager logic here.
|
||||||
|
|
||||||
|
This method **must** be decorated with
|
||||||
|
:func:`@contextmanager <contextlib.contextmanager>`.
|
||||||
|
|
||||||
|
.. note:: Remember that the ``yield`` will raise any exception raised in the
|
||||||
|
enclosed context block, so use a ``finally:`` block to clean up resources!
|
||||||
|
|
||||||
|
:return: a context manager object
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class AsyncContextManagerMixin:
|
||||||
|
"""
|
||||||
|
Mixin class providing async context manager functionality via a generator-based
|
||||||
|
implementation.
|
||||||
|
|
||||||
|
This class allows you to implement a context manager via
|
||||||
|
:meth:`__asynccontextmanager__`. The mechanics are meant to mirror those of
|
||||||
|
:func:`@asynccontextmanager <contextlib.asynccontextmanager>`.
|
||||||
|
|
||||||
|
.. note:: Classes using this mix-in are not reentrant as context managers, meaning
|
||||||
|
that once you enter it, you can't re-enter before first exiting it.
|
||||||
|
|
||||||
|
.. seealso:: :doc:`contextmanagers`
|
||||||
|
"""
|
||||||
|
|
||||||
|
__cm: AbstractAsyncContextManager[object, bool | None] | None = None
|
||||||
|
|
||||||
|
@final
|
||||||
|
async def __aenter__(self: _SupportsAsyncCtxMgr[_T_co, bool | None]) -> _T_co:
|
||||||
|
# Needed for mypy to assume self still has the __cm member
|
||||||
|
assert isinstance(self, AsyncContextManagerMixin)
|
||||||
|
if self.__cm is not None:
|
||||||
|
raise RuntimeError(
|
||||||
|
f"this {self.__class__.__qualname__} has already been entered"
|
||||||
|
)
|
||||||
|
|
||||||
|
cm = self.__asynccontextmanager__()
|
||||||
|
if not isinstance(cm, AbstractAsyncContextManager):
|
||||||
|
if isasyncgen(cm):
|
||||||
|
raise TypeError(
|
||||||
|
"__asynccontextmanager__() returned an async generator instead of "
|
||||||
|
"an async context manager. Did you forget to add the "
|
||||||
|
"@asynccontextmanager decorator?"
|
||||||
|
)
|
||||||
|
elif iscoroutine(cm):
|
||||||
|
cm.close()
|
||||||
|
raise TypeError(
|
||||||
|
"__asynccontextmanager__() returned a coroutine object instead of "
|
||||||
|
"an async context manager. Did you forget to add the "
|
||||||
|
"@asynccontextmanager decorator and a 'yield' statement?"
|
||||||
|
)
|
||||||
|
|
||||||
|
raise TypeError(
|
||||||
|
f"__asynccontextmanager__() did not return an async context manager, "
|
||||||
|
f"but {cm.__class__!r}"
|
||||||
|
)
|
||||||
|
|
||||||
|
if cm is self:
|
||||||
|
raise TypeError(
|
||||||
|
f"{self.__class__.__qualname__}.__asynccontextmanager__() returned "
|
||||||
|
f"self. Did you forget to add the @asynccontextmanager decorator and a "
|
||||||
|
f"'yield' statement?"
|
||||||
|
)
|
||||||
|
|
||||||
|
value = await cm.__aenter__()
|
||||||
|
self.__cm = cm
|
||||||
|
return value
|
||||||
|
|
||||||
|
@final
|
||||||
|
async def __aexit__(
|
||||||
|
self: _SupportsAsyncCtxMgr[object, _ExitT_co],
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> _ExitT_co:
|
||||||
|
assert isinstance(self, AsyncContextManagerMixin)
|
||||||
|
if self.__cm is None:
|
||||||
|
raise RuntimeError(
|
||||||
|
f"this {self.__class__.__qualname__} has not been entered yet"
|
||||||
|
)
|
||||||
|
|
||||||
|
# Prevent circular references
|
||||||
|
cm = self.__cm
|
||||||
|
del self.__cm
|
||||||
|
|
||||||
|
return cast(_ExitT_co, await cm.__aexit__(exc_type, exc_val, exc_tb))
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
def __asynccontextmanager__(
|
||||||
|
self,
|
||||||
|
) -> AbstractAsyncContextManager[object, bool | None]:
|
||||||
|
"""
|
||||||
|
Implement your async context manager logic here.
|
||||||
|
|
||||||
|
This method **must** be decorated with
|
||||||
|
:func:`@asynccontextmanager <contextlib.asynccontextmanager>`.
|
||||||
|
|
||||||
|
.. note:: Remember that the ``yield`` will raise any exception raised in the
|
||||||
|
enclosed context block, so use a ``finally:`` block to clean up resources!
|
||||||
|
|
||||||
|
:return: an async context manager object
|
||||||
|
"""
|
||||||
@@ -0,0 +1,240 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import math
|
||||||
|
import sys
|
||||||
|
import threading
|
||||||
|
from collections.abc import Awaitable, Callable, Generator
|
||||||
|
from contextlib import contextmanager
|
||||||
|
from contextvars import Token
|
||||||
|
from importlib import import_module
|
||||||
|
from typing import TYPE_CHECKING, Any, TypeVar
|
||||||
|
|
||||||
|
from ._exceptions import NoEventLoopError
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import TypeVarTuple, Unpack
|
||||||
|
else:
|
||||||
|
from typing_extensions import TypeVarTuple, Unpack
|
||||||
|
|
||||||
|
sniffio: Any
|
||||||
|
try:
|
||||||
|
import sniffio
|
||||||
|
except ModuleNotFoundError:
|
||||||
|
sniffio = None
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
from ..abc import AsyncBackend
|
||||||
|
|
||||||
|
# This must be updated when new backends are introduced
|
||||||
|
BACKENDS = "asyncio", "trio"
|
||||||
|
|
||||||
|
T_Retval = TypeVar("T_Retval")
|
||||||
|
PosArgsT = TypeVarTuple("PosArgsT")
|
||||||
|
|
||||||
|
threadlocals = threading.local()
|
||||||
|
loaded_backends: dict[str, type[AsyncBackend]] = {}
|
||||||
|
|
||||||
|
|
||||||
|
def run(
|
||||||
|
func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval]],
|
||||||
|
*args: Unpack[PosArgsT],
|
||||||
|
backend: str = "asyncio",
|
||||||
|
backend_options: dict[str, Any] | None = None,
|
||||||
|
) -> T_Retval:
|
||||||
|
"""
|
||||||
|
Run the given coroutine function in an asynchronous event loop.
|
||||||
|
|
||||||
|
The current thread must not be already running an event loop.
|
||||||
|
|
||||||
|
:param func: a coroutine function
|
||||||
|
:param args: positional arguments to ``func``
|
||||||
|
:param backend: name of the asynchronous event loop implementation – currently
|
||||||
|
either ``asyncio`` or ``trio``
|
||||||
|
:param backend_options: keyword arguments to call the backend ``run()``
|
||||||
|
implementation with (documented :ref:`here <backend options>`)
|
||||||
|
:return: the return value of the coroutine function
|
||||||
|
:raises RuntimeError: if an asynchronous event loop is already running in this
|
||||||
|
thread
|
||||||
|
:raises LookupError: if the named backend is not found
|
||||||
|
|
||||||
|
"""
|
||||||
|
if asynclib_name := current_async_library():
|
||||||
|
raise RuntimeError(f"Already running {asynclib_name} in this thread")
|
||||||
|
|
||||||
|
try:
|
||||||
|
async_backend = get_async_backend(backend)
|
||||||
|
except ImportError as exc:
|
||||||
|
if backend in BACKENDS:
|
||||||
|
raise LookupError(
|
||||||
|
f"Backend {backend!r} is not available. "
|
||||||
|
f"Install it with: pip install anyio[{backend}]"
|
||||||
|
) from exc
|
||||||
|
|
||||||
|
raise LookupError(f"No such backend: {backend}") from exc
|
||||||
|
|
||||||
|
token = None
|
||||||
|
if asynclib_name is None:
|
||||||
|
# Since we're in control of the event loop, we can cache the name of the async
|
||||||
|
# library
|
||||||
|
token = set_current_async_library(backend)
|
||||||
|
|
||||||
|
try:
|
||||||
|
backend_options = backend_options or {}
|
||||||
|
return async_backend.run(func, args, {}, backend_options)
|
||||||
|
finally:
|
||||||
|
reset_current_async_library(token)
|
||||||
|
|
||||||
|
|
||||||
|
async def sleep(delay: float) -> None:
|
||||||
|
"""
|
||||||
|
Pause the current task for the specified duration.
|
||||||
|
|
||||||
|
:param delay: the duration, in seconds
|
||||||
|
|
||||||
|
"""
|
||||||
|
return await get_async_backend().sleep(delay)
|
||||||
|
|
||||||
|
|
||||||
|
async def sleep_forever() -> None:
|
||||||
|
"""
|
||||||
|
Pause the current task until it's cancelled.
|
||||||
|
|
||||||
|
This is a shortcut for ``sleep(math.inf)``.
|
||||||
|
|
||||||
|
.. versionadded:: 3.1
|
||||||
|
|
||||||
|
"""
|
||||||
|
await sleep(math.inf)
|
||||||
|
|
||||||
|
|
||||||
|
async def sleep_until(deadline: float) -> None:
|
||||||
|
"""
|
||||||
|
Pause the current task until the given time.
|
||||||
|
|
||||||
|
:param deadline: the absolute time to wake up at (according to the internal
|
||||||
|
monotonic clock of the event loop)
|
||||||
|
|
||||||
|
.. versionadded:: 3.1
|
||||||
|
|
||||||
|
"""
|
||||||
|
now = current_time()
|
||||||
|
await sleep(max(deadline - now, 0))
|
||||||
|
|
||||||
|
|
||||||
|
def current_time() -> float:
|
||||||
|
"""
|
||||||
|
Return the current value of the event loop's internal clock.
|
||||||
|
|
||||||
|
:return: the clock value (seconds)
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
"""
|
||||||
|
return get_async_backend().current_time()
|
||||||
|
|
||||||
|
|
||||||
|
def get_all_backends() -> tuple[str, ...]:
|
||||||
|
"""Return a tuple of the names of all built-in backends."""
|
||||||
|
return BACKENDS
|
||||||
|
|
||||||
|
|
||||||
|
def get_available_backends() -> tuple[str, ...]:
|
||||||
|
"""
|
||||||
|
Test for the availability of built-in backends.
|
||||||
|
|
||||||
|
:return a tuple of the built-in backend names that were successfully imported
|
||||||
|
|
||||||
|
.. versionadded:: 4.12
|
||||||
|
|
||||||
|
"""
|
||||||
|
available_backends: list[str] = []
|
||||||
|
for backend_name in get_all_backends():
|
||||||
|
try:
|
||||||
|
get_async_backend(backend_name)
|
||||||
|
except ImportError:
|
||||||
|
continue
|
||||||
|
|
||||||
|
available_backends.append(backend_name)
|
||||||
|
|
||||||
|
return tuple(available_backends)
|
||||||
|
|
||||||
|
|
||||||
|
def get_cancelled_exc_class() -> type[BaseException]:
|
||||||
|
"""
|
||||||
|
Return the current async library's cancellation exception class.
|
||||||
|
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
"""
|
||||||
|
return get_async_backend().cancelled_exception_class()
|
||||||
|
|
||||||
|
|
||||||
|
#
|
||||||
|
# Private API
|
||||||
|
#
|
||||||
|
|
||||||
|
|
||||||
|
@contextmanager
|
||||||
|
def claim_worker_thread(
|
||||||
|
backend_class: type[AsyncBackend], token: object
|
||||||
|
) -> Generator[Any, None, None]:
|
||||||
|
from ..lowlevel import EventLoopToken
|
||||||
|
|
||||||
|
threadlocals.current_token = EventLoopToken(backend_class, token)
|
||||||
|
try:
|
||||||
|
yield
|
||||||
|
finally:
|
||||||
|
del threadlocals.current_token
|
||||||
|
|
||||||
|
|
||||||
|
def get_async_backend(asynclib_name: str | None = None) -> type[AsyncBackend]:
|
||||||
|
if asynclib_name is None:
|
||||||
|
asynclib_name = current_async_library()
|
||||||
|
if not asynclib_name:
|
||||||
|
raise NoEventLoopError(
|
||||||
|
f"Not currently running on any asynchronous event loop. "
|
||||||
|
f"Available async backends: {', '.join(get_all_backends())}"
|
||||||
|
)
|
||||||
|
|
||||||
|
# We use our own dict instead of sys.modules to get the already imported back-end
|
||||||
|
# class because the appropriate modules in sys.modules could potentially be only
|
||||||
|
# partially initialized
|
||||||
|
try:
|
||||||
|
return loaded_backends[asynclib_name]
|
||||||
|
except KeyError:
|
||||||
|
module = import_module(f"anyio._backends._{asynclib_name}")
|
||||||
|
loaded_backends[asynclib_name] = module.backend_class
|
||||||
|
return module.backend_class
|
||||||
|
|
||||||
|
|
||||||
|
def current_async_library() -> str | None:
|
||||||
|
if sniffio is None:
|
||||||
|
# If sniffio is not installed, we assume we're either running asyncio or nothing
|
||||||
|
import asyncio
|
||||||
|
|
||||||
|
try:
|
||||||
|
asyncio.get_running_loop()
|
||||||
|
return "asyncio"
|
||||||
|
except RuntimeError:
|
||||||
|
pass
|
||||||
|
else:
|
||||||
|
try:
|
||||||
|
return sniffio.current_async_library()
|
||||||
|
except sniffio.AsyncLibraryNotFoundError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def set_current_async_library(asynclib_name: str | None) -> Token | None:
|
||||||
|
# no-op if sniffio is not installed
|
||||||
|
if sniffio is None:
|
||||||
|
return None
|
||||||
|
|
||||||
|
return sniffio.current_async_library_cvar.set(asynclib_name)
|
||||||
|
|
||||||
|
|
||||||
|
def reset_current_async_library(token: Token | None) -> None:
|
||||||
|
if token is not None:
|
||||||
|
sniffio.current_async_library_cvar.reset(token)
|
||||||
@@ -0,0 +1,205 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import sys
|
||||||
|
from collections.abc import Generator
|
||||||
|
from textwrap import dedent
|
||||||
|
from typing import Any
|
||||||
|
|
||||||
|
if sys.version_info < (3, 11):
|
||||||
|
from exceptiongroup import BaseExceptionGroup
|
||||||
|
|
||||||
|
|
||||||
|
class BrokenResourceError(Exception):
|
||||||
|
"""
|
||||||
|
Raised when trying to use a resource that has been rendered unusable due to external
|
||||||
|
causes (e.g. a send stream whose peer has disconnected).
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class BrokenWorkerProcess(Exception):
|
||||||
|
"""
|
||||||
|
Raised by :meth:`~anyio.to_process.run_sync` if the worker process terminates abruptly or
|
||||||
|
otherwise misbehaves.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class BrokenWorkerInterpreter(Exception):
|
||||||
|
"""
|
||||||
|
Raised by :meth:`~anyio.to_interpreter.run_sync` if an unexpected exception is
|
||||||
|
raised in the subinterpreter.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, excinfo: Any):
|
||||||
|
# This was adapted from concurrent.futures.interpreter.ExecutionFailed
|
||||||
|
msg = excinfo.formatted
|
||||||
|
if not msg:
|
||||||
|
if excinfo.type and excinfo.msg:
|
||||||
|
msg = f"{excinfo.type.__name__}: {excinfo.msg}"
|
||||||
|
else:
|
||||||
|
msg = excinfo.type.__name__ or excinfo.msg
|
||||||
|
|
||||||
|
super().__init__(msg)
|
||||||
|
self.excinfo = excinfo
|
||||||
|
|
||||||
|
def __str__(self) -> str:
|
||||||
|
try:
|
||||||
|
formatted = self.excinfo.errdisplay
|
||||||
|
except Exception:
|
||||||
|
return super().__str__()
|
||||||
|
else:
|
||||||
|
return dedent(
|
||||||
|
f"""
|
||||||
|
{super().__str__()}
|
||||||
|
|
||||||
|
Uncaught in the interpreter:
|
||||||
|
|
||||||
|
{formatted}
|
||||||
|
""".strip()
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class BusyResourceError(Exception):
|
||||||
|
"""
|
||||||
|
Raised when two tasks are trying to read from or write to the same resource
|
||||||
|
concurrently.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, action: str):
|
||||||
|
super().__init__(f"Another task is already {action} this resource")
|
||||||
|
|
||||||
|
|
||||||
|
class ClosedResourceError(Exception):
|
||||||
|
"""Raised when trying to use a resource that has been closed."""
|
||||||
|
|
||||||
|
|
||||||
|
class ConnectionFailed(OSError):
|
||||||
|
"""
|
||||||
|
Raised when a connection attempt fails.
|
||||||
|
|
||||||
|
.. note:: This class inherits from :exc:`OSError` for backwards compatibility.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
def iterate_exceptions(
|
||||||
|
exception: BaseException,
|
||||||
|
) -> Generator[BaseException, None, None]:
|
||||||
|
if isinstance(exception, BaseExceptionGroup):
|
||||||
|
for exc in exception.exceptions:
|
||||||
|
yield from iterate_exceptions(exc)
|
||||||
|
else:
|
||||||
|
yield exception
|
||||||
|
|
||||||
|
|
||||||
|
class DelimiterNotFound(Exception):
|
||||||
|
"""
|
||||||
|
Raised during
|
||||||
|
:meth:`~anyio.streams.buffered.BufferedByteReceiveStream.receive_until` if the
|
||||||
|
maximum number of bytes has been read without the delimiter being found.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, max_bytes: int) -> None:
|
||||||
|
super().__init__(
|
||||||
|
f"The delimiter was not found among the first {max_bytes} bytes"
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class EndOfStream(Exception):
|
||||||
|
"""
|
||||||
|
Raised when trying to read from a stream that has been closed from the other end.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class IncompleteRead(Exception):
|
||||||
|
"""
|
||||||
|
Raised during
|
||||||
|
:meth:`~anyio.streams.buffered.BufferedByteReceiveStream.receive_exactly` or
|
||||||
|
:meth:`~anyio.streams.buffered.BufferedByteReceiveStream.receive_until` if the
|
||||||
|
connection is closed before the requested amount of bytes has been read.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self) -> None:
|
||||||
|
super().__init__(
|
||||||
|
"The stream was closed before the read operation could be completed"
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class TypedAttributeLookupError(LookupError):
|
||||||
|
"""
|
||||||
|
Raised by :meth:`~anyio.TypedAttributeProvider.extra` when the given typed attribute
|
||||||
|
is not found and no default value has been given.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class WouldBlock(Exception):
|
||||||
|
"""Raised by ``X_nowait`` functions if ``X()`` would block."""
|
||||||
|
|
||||||
|
|
||||||
|
class NoEventLoopError(RuntimeError):
|
||||||
|
"""
|
||||||
|
Raised by several functions that require an event loop to be running in the current
|
||||||
|
thread when there is no running event loop.
|
||||||
|
|
||||||
|
This is also raised by :func:`.from_thread.run` and :func:`.from_thread.run_sync`
|
||||||
|
if not calling from an AnyIO worker thread, and no ``token`` was passed.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class RunFinishedError(RuntimeError):
|
||||||
|
"""
|
||||||
|
Raised by :func:`.from_thread.run` and :func:`.from_thread.run_sync` if the event
|
||||||
|
loop associated with the explicitly passed token has already finished.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self) -> None:
|
||||||
|
super().__init__(
|
||||||
|
"The event loop associated with the given token has already finished"
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class TaskFailed(Exception):
|
||||||
|
"""
|
||||||
|
Raised when awaiting on, or attempting to access the return value of, a
|
||||||
|
:class:`.TaskHandle` that raised an exception.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class TaskCancelled(TaskFailed):
|
||||||
|
"""
|
||||||
|
Raised when awaiting on, or attempting to access the return value of, a
|
||||||
|
:class:`.TaskHandle` that was cancelled.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class TaskNotFinished(Exception):
|
||||||
|
"""
|
||||||
|
Raised when attempting to access the return value or exception of a
|
||||||
|
:class:`.TaskHandle` that is still pending completion.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class FutureFailed(Exception):
|
||||||
|
"""
|
||||||
|
Raised when awaiting on, or attempting to access the return value of, a
|
||||||
|
:class:`.Future` that raised an exception.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class FutureCancelled(FutureFailed):
|
||||||
|
"""
|
||||||
|
Raised when attempting to access the return value or exception of a
|
||||||
|
:class:`.Future` that was cancelled.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class FutureNotFinished(Exception):
|
||||||
|
"""
|
||||||
|
Raised when attempting to access the return value or exception of a
|
||||||
|
:class:`.Future` that is still pending completion.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class FutureAlreadyFinished(Exception):
|
||||||
|
"""
|
||||||
|
Raised when attempting set a result of or await a
|
||||||
|
:class:`.Future` that has already completed.
|
||||||
|
"""
|
||||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,191 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from collections.abc import Generator
|
||||||
|
from enum import Enum, auto
|
||||||
|
from typing import Any, Generic, TypeVar
|
||||||
|
|
||||||
|
from ._exceptions import (
|
||||||
|
FutureAlreadyFinished,
|
||||||
|
FutureCancelled,
|
||||||
|
FutureFailed,
|
||||||
|
FutureNotFinished,
|
||||||
|
)
|
||||||
|
from ._synchronization import Event
|
||||||
|
|
||||||
|
T = TypeVar("T")
|
||||||
|
|
||||||
|
|
||||||
|
class Future(Generic[T]):
|
||||||
|
"""
|
||||||
|
An awaitable object that works similar to a :class:`asyncio.Future` but
|
||||||
|
with similar characteristics to a :class:`.TaskHandle`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
class Status(Enum):
|
||||||
|
"""
|
||||||
|
The status of a future handle.
|
||||||
|
|
||||||
|
.. attribute:: PENDING
|
||||||
|
|
||||||
|
The future has not finished yet.
|
||||||
|
.. attribute:: FINISHED
|
||||||
|
|
||||||
|
The future has finished with a return value.
|
||||||
|
.. attribute:: CANCELLED
|
||||||
|
|
||||||
|
The future was cancelled and has finished since.
|
||||||
|
.. attribute:: FAILED
|
||||||
|
|
||||||
|
The future raised an exception.
|
||||||
|
"""
|
||||||
|
|
||||||
|
PENDING = auto()
|
||||||
|
FINISHED = auto()
|
||||||
|
CANCELLED = auto()
|
||||||
|
FAILED = auto()
|
||||||
|
|
||||||
|
__slots__ = (
|
||||||
|
"_cancelled",
|
||||||
|
"_exception",
|
||||||
|
"_finished_event",
|
||||||
|
"_name",
|
||||||
|
"_return_value",
|
||||||
|
)
|
||||||
|
_return_value: T
|
||||||
|
|
||||||
|
def __init__(self, *, name: str | None = None) -> None:
|
||||||
|
self._finished_event = Event()
|
||||||
|
self._exception: BaseException | None = None
|
||||||
|
self._cancelled: bool = False
|
||||||
|
self._name = name
|
||||||
|
|
||||||
|
def _check_pending(self) -> None:
|
||||||
|
"""Shortcut for checking if a Future is pending
|
||||||
|
|
||||||
|
:raises FutureAlreadyFinished: if future was already given a result or exception.
|
||||||
|
:raises FutureCancelled: if future has been cancelled previously.
|
||||||
|
"""
|
||||||
|
match self.status:
|
||||||
|
case Future.Status.PENDING:
|
||||||
|
return
|
||||||
|
case Future.Status.FINISHED:
|
||||||
|
raise FutureAlreadyFinished("future has already finished")
|
||||||
|
case Future.Status.FAILED:
|
||||||
|
raise FutureAlreadyFinished("future already failed")
|
||||||
|
case Future.Status.CANCELLED:
|
||||||
|
raise FutureCancelled("future was cancelled")
|
||||||
|
|
||||||
|
async def wait(self) -> None:
|
||||||
|
"""
|
||||||
|
Waits for the future to finish.
|
||||||
|
|
||||||
|
This method will attempt to wait for a result or exception
|
||||||
|
"""
|
||||||
|
await self._finished_event.wait()
|
||||||
|
|
||||||
|
def cancel(self) -> None:
|
||||||
|
"""Cancels a pending `.Future` object
|
||||||
|
|
||||||
|
Does nothing if the Future was already finished.
|
||||||
|
"""
|
||||||
|
if self.status is Future.Status.PENDING:
|
||||||
|
self._cancelled = True
|
||||||
|
self._finished_event.set()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def exception(self) -> BaseException | None:
|
||||||
|
"""
|
||||||
|
The exception value of a `.Future`
|
||||||
|
|
||||||
|
:raises FutureNotFinished: if future is still pending
|
||||||
|
:raises FutureCancelled: if future was cancelled
|
||||||
|
:returns: None if future succeeds with a result sent instead
|
||||||
|
otherwise this will be an exception
|
||||||
|
"""
|
||||||
|
|
||||||
|
match self.status:
|
||||||
|
case Future.Status.PENDING:
|
||||||
|
raise FutureNotFinished("the future has not finished yet")
|
||||||
|
case Future.Status.FINISHED:
|
||||||
|
return None
|
||||||
|
case Future.Status.CANCELLED:
|
||||||
|
raise FutureCancelled("the future was cancelled")
|
||||||
|
case Future.Status.FAILED:
|
||||||
|
return self._exception
|
||||||
|
|
||||||
|
@exception.setter
|
||||||
|
def exception(self, exception: BaseException) -> None:
|
||||||
|
"""Send exception for a `.Future` object
|
||||||
|
|
||||||
|
:raises FutureAlreadyFinished: if future was already given a result or exception.
|
||||||
|
:raises FutureCancelled: if future has been cancelled previously.
|
||||||
|
"""
|
||||||
|
self._check_pending()
|
||||||
|
self._exception = exception
|
||||||
|
self._finished_event.set()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def return_value(self) -> T:
|
||||||
|
"""
|
||||||
|
The return value of the future.
|
||||||
|
|
||||||
|
:raises FutureNotFinished: if the future has not finished yet
|
||||||
|
:raises FutureCancelled: if the future was cancelled
|
||||||
|
:raises FutureFailed: if the future raised an exception
|
||||||
|
|
||||||
|
"""
|
||||||
|
match self.status:
|
||||||
|
case Future.Status.PENDING:
|
||||||
|
raise FutureNotFinished("the future has not finished yet")
|
||||||
|
case Future.Status.FINISHED:
|
||||||
|
return self._return_value
|
||||||
|
case Future.Status.CANCELLED:
|
||||||
|
raise FutureCancelled("the future was cancelled")
|
||||||
|
case Future.Status.FAILED:
|
||||||
|
raise FutureFailed(
|
||||||
|
"the future raised an exception"
|
||||||
|
) from self._exception
|
||||||
|
|
||||||
|
@return_value.setter
|
||||||
|
def return_value(self, value: T) -> None:
|
||||||
|
"""
|
||||||
|
Send pending result for a `.Future` object
|
||||||
|
|
||||||
|
:raises FutureAlreadyFinished: if future was already given a result or exception.
|
||||||
|
:raises FutureCancelled: if future has been cancelled previously.
|
||||||
|
"""
|
||||||
|
self._check_pending()
|
||||||
|
self._return_value = value
|
||||||
|
self._finished_event.set()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def status(self) -> Future.Status:
|
||||||
|
"""
|
||||||
|
The current status of a future.
|
||||||
|
|
||||||
|
Every future starts in the :attr:`~Future.Status.PENDING` state.
|
||||||
|
If a future is cancelled while in this state, it will transition to the
|
||||||
|
:attr:`Future.Status.CANCELLED` state. When the task finishes, it will
|
||||||
|
transition to one of the three final states (
|
||||||
|
:attr:`Future.Status.FINISHED`, :attr:`Future.Status.FAILED`, or
|
||||||
|
:attr:`Future.Status.CANCELLED`) depending on the exception the task
|
||||||
|
raised, if any. No other status transitions will happen.
|
||||||
|
"""
|
||||||
|
if not self._finished_event.is_set():
|
||||||
|
return Future.Status.PENDING
|
||||||
|
elif self._cancelled:
|
||||||
|
return Future.Status.CANCELLED
|
||||||
|
elif self._exception is not None:
|
||||||
|
return Future.Status.FAILED
|
||||||
|
else:
|
||||||
|
return Future.Status.FINISHED
|
||||||
|
|
||||||
|
def __await__(self) -> Generator[Any, Any, T]:
|
||||||
|
yield from self.wait().__await__()
|
||||||
|
return self.return_value
|
||||||
|
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
return (
|
||||||
|
f"<{self.__class__.__name__} {self.status.name.lower()} "
|
||||||
|
f"name={self._name!r}>"
|
||||||
|
)
|
||||||
@@ -0,0 +1,18 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from ..abc import AsyncResource # noqa: TC001
|
||||||
|
from ._tasks import CancelScope
|
||||||
|
|
||||||
|
|
||||||
|
async def aclose_forcefully(resource: AsyncResource) -> None:
|
||||||
|
"""
|
||||||
|
Close an asynchronous resource in a cancelled scope.
|
||||||
|
|
||||||
|
Doing this closes the resource without waiting on anything.
|
||||||
|
|
||||||
|
:param resource: the resource to close
|
||||||
|
|
||||||
|
"""
|
||||||
|
with CancelScope() as scope:
|
||||||
|
scope.cancel()
|
||||||
|
await resource.aclose()
|
||||||
@@ -0,0 +1,29 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from collections.abc import AsyncIterator
|
||||||
|
from contextlib import AbstractContextManager
|
||||||
|
from signal import Signals
|
||||||
|
|
||||||
|
from ._eventloop import get_async_backend
|
||||||
|
|
||||||
|
|
||||||
|
def open_signal_receiver(
|
||||||
|
*signals: Signals,
|
||||||
|
) -> AbstractContextManager[AsyncIterator[Signals]]:
|
||||||
|
"""
|
||||||
|
Start receiving operating system signals.
|
||||||
|
|
||||||
|
:param signals: signals to receive (e.g. ``signal.SIGINT``)
|
||||||
|
:return: an asynchronous context manager for an asynchronous iterator which yields
|
||||||
|
signal numbers
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
.. warning:: Windows does not support signals natively so it is best to avoid
|
||||||
|
relying on this in cross-platform applications.
|
||||||
|
|
||||||
|
.. warning:: On asyncio, this permanently replaces any previous signal handler for
|
||||||
|
the given signals, as set via :meth:`~asyncio.loop.add_signal_handler`.
|
||||||
|
|
||||||
|
"""
|
||||||
|
return get_async_backend().open_signal_receiver(*signals)
|
||||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,52 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import math
|
||||||
|
from typing import TypeVar
|
||||||
|
from warnings import warn
|
||||||
|
|
||||||
|
from ..streams.memory import (
|
||||||
|
MemoryObjectReceiveStream,
|
||||||
|
MemoryObjectSendStream,
|
||||||
|
_MemoryObjectStreamState,
|
||||||
|
)
|
||||||
|
|
||||||
|
T_Item = TypeVar("T_Item")
|
||||||
|
|
||||||
|
|
||||||
|
class create_memory_object_stream(
|
||||||
|
tuple[MemoryObjectSendStream[T_Item], MemoryObjectReceiveStream[T_Item]],
|
||||||
|
):
|
||||||
|
"""
|
||||||
|
Create a memory object stream.
|
||||||
|
|
||||||
|
The stream's item type can be annotated like
|
||||||
|
:func:`create_memory_object_stream[T_Item]`.
|
||||||
|
|
||||||
|
:param max_buffer_size: number of items held in the buffer until ``send()`` starts
|
||||||
|
blocking
|
||||||
|
:param item_type: old way of marking the streams with the right generic type for
|
||||||
|
static typing (does nothing on AnyIO 4)
|
||||||
|
|
||||||
|
.. deprecated:: 4.0
|
||||||
|
Use ``create_memory_object_stream[YourItemType](...)`` instead.
|
||||||
|
:return: a tuple of (send stream, receive stream)
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __new__( # type: ignore[misc]
|
||||||
|
cls, max_buffer_size: float = 0, item_type: object = None
|
||||||
|
) -> tuple[MemoryObjectSendStream[T_Item], MemoryObjectReceiveStream[T_Item]]:
|
||||||
|
if max_buffer_size != math.inf and not isinstance(max_buffer_size, int):
|
||||||
|
raise ValueError("max_buffer_size must be either an integer or math.inf")
|
||||||
|
if max_buffer_size < 0:
|
||||||
|
raise ValueError("max_buffer_size cannot be negative")
|
||||||
|
if item_type is not None:
|
||||||
|
warn(
|
||||||
|
"The item_type argument has been deprecated in AnyIO 4.0. "
|
||||||
|
"Use create_memory_object_stream[YourItemType](...) instead.",
|
||||||
|
DeprecationWarning,
|
||||||
|
stacklevel=2,
|
||||||
|
)
|
||||||
|
|
||||||
|
state = _MemoryObjectStreamState[T_Item](max_buffer_size)
|
||||||
|
return (MemoryObjectSendStream(state), MemoryObjectReceiveStream(state))
|
||||||
@@ -0,0 +1,196 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from collections.abc import AsyncIterable, Iterable, Mapping, Sequence
|
||||||
|
from io import BytesIO
|
||||||
|
from os import PathLike
|
||||||
|
from subprocess import PIPE, CalledProcessError, CompletedProcess
|
||||||
|
from typing import IO, Any, TypeAlias, cast
|
||||||
|
|
||||||
|
from ..abc import Process # noqa: TC001
|
||||||
|
from ._eventloop import get_async_backend
|
||||||
|
from ._tasks import create_task_group
|
||||||
|
|
||||||
|
StrOrBytesPath: TypeAlias = str | bytes | PathLike[str] | PathLike[bytes]
|
||||||
|
|
||||||
|
|
||||||
|
async def run_process(
|
||||||
|
command: StrOrBytesPath | Sequence[StrOrBytesPath],
|
||||||
|
*,
|
||||||
|
input: bytes | None = None,
|
||||||
|
stdin: int | IO[Any] | None = None,
|
||||||
|
stdout: int | IO[Any] | None = PIPE,
|
||||||
|
stderr: int | IO[Any] | None = PIPE,
|
||||||
|
check: bool = True,
|
||||||
|
cwd: StrOrBytesPath | None = None,
|
||||||
|
env: Mapping[str, str] | None = None,
|
||||||
|
startupinfo: Any = None,
|
||||||
|
creationflags: int = 0,
|
||||||
|
start_new_session: bool = False,
|
||||||
|
pass_fds: Sequence[int] = (),
|
||||||
|
user: str | int | None = None,
|
||||||
|
group: str | int | None = None,
|
||||||
|
extra_groups: Iterable[str | int] | None = None,
|
||||||
|
umask: int = -1,
|
||||||
|
) -> CompletedProcess[bytes]:
|
||||||
|
"""
|
||||||
|
Run an external command in a subprocess and wait until it completes.
|
||||||
|
|
||||||
|
.. seealso:: :func:`subprocess.run`
|
||||||
|
|
||||||
|
:param command: either a string to pass to the shell, or an iterable of strings
|
||||||
|
containing the executable name or path and its arguments
|
||||||
|
:param input: bytes passed to the standard input of the subprocess
|
||||||
|
:param stdin: one of :data:`subprocess.PIPE`, :data:`subprocess.DEVNULL`,
|
||||||
|
a file-like object, or `None`; ``input`` overrides this
|
||||||
|
:param stdout: one of :data:`subprocess.PIPE`, :data:`subprocess.DEVNULL`,
|
||||||
|
a file-like object, or `None`
|
||||||
|
:param stderr: one of :data:`subprocess.PIPE`, :data:`subprocess.DEVNULL`,
|
||||||
|
:data:`subprocess.STDOUT`, a file-like object, or `None`
|
||||||
|
:param check: if ``True``, raise :exc:`~subprocess.CalledProcessError` if the
|
||||||
|
process terminates with a return code other than 0
|
||||||
|
:param cwd: If not ``None``, change the working directory to this before running the
|
||||||
|
command
|
||||||
|
:param env: if not ``None``, this mapping replaces the inherited environment
|
||||||
|
variables from the parent process
|
||||||
|
:param startupinfo: an instance of :class:`subprocess.STARTUPINFO` that can be used
|
||||||
|
to specify process startup parameters (Windows only)
|
||||||
|
:param creationflags: flags that can be used to control the creation of the
|
||||||
|
subprocess (see :class:`subprocess.Popen` for the specifics)
|
||||||
|
:param start_new_session: if ``true`` the setsid() system call will be made in the
|
||||||
|
child process prior to the execution of the subprocess. (POSIX only)
|
||||||
|
:param pass_fds: sequence of file descriptors to keep open between the parent and
|
||||||
|
child processes. (POSIX only)
|
||||||
|
:param user: effective user to run the process as (Python >= 3.9, POSIX only)
|
||||||
|
:param group: effective group to run the process as (Python >= 3.9, POSIX only)
|
||||||
|
:param extra_groups: supplementary groups to set in the subprocess (Python >= 3.9,
|
||||||
|
POSIX only)
|
||||||
|
:param umask: if not negative, this umask is applied in the child process before
|
||||||
|
running the given command (Python >= 3.9, POSIX only)
|
||||||
|
:return: an object representing the completed process
|
||||||
|
:raises ~subprocess.CalledProcessError: if ``check`` is ``True`` and the process
|
||||||
|
exits with a nonzero return code
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
async def drain_stream(stream: AsyncIterable[bytes], index: int) -> None:
|
||||||
|
buffer = BytesIO()
|
||||||
|
async for chunk in stream:
|
||||||
|
buffer.write(chunk)
|
||||||
|
|
||||||
|
stream_contents[index] = buffer.getvalue()
|
||||||
|
|
||||||
|
if stdin is not None and input is not None:
|
||||||
|
raise ValueError("only one of stdin and input is allowed")
|
||||||
|
|
||||||
|
async with await open_process(
|
||||||
|
command,
|
||||||
|
stdin=PIPE if input else stdin,
|
||||||
|
stdout=stdout,
|
||||||
|
stderr=stderr,
|
||||||
|
cwd=cwd,
|
||||||
|
env=env,
|
||||||
|
startupinfo=startupinfo,
|
||||||
|
creationflags=creationflags,
|
||||||
|
start_new_session=start_new_session,
|
||||||
|
pass_fds=pass_fds,
|
||||||
|
user=user,
|
||||||
|
group=group,
|
||||||
|
extra_groups=extra_groups,
|
||||||
|
umask=umask,
|
||||||
|
) as process:
|
||||||
|
stream_contents: list[bytes | None] = [None, None]
|
||||||
|
async with create_task_group() as tg:
|
||||||
|
if process.stdout:
|
||||||
|
tg.start_soon(drain_stream, process.stdout, 0)
|
||||||
|
|
||||||
|
if process.stderr:
|
||||||
|
tg.start_soon(drain_stream, process.stderr, 1)
|
||||||
|
|
||||||
|
if process.stdin and input:
|
||||||
|
await process.stdin.send(input)
|
||||||
|
await process.stdin.aclose()
|
||||||
|
|
||||||
|
await process.wait()
|
||||||
|
|
||||||
|
output, errors = stream_contents
|
||||||
|
if check and process.returncode != 0:
|
||||||
|
raise CalledProcessError(cast(int, process.returncode), command, output, errors)
|
||||||
|
|
||||||
|
return CompletedProcess(command, cast(int, process.returncode), output, errors)
|
||||||
|
|
||||||
|
|
||||||
|
async def open_process(
|
||||||
|
command: StrOrBytesPath | Sequence[StrOrBytesPath],
|
||||||
|
*,
|
||||||
|
stdin: int | IO[Any] | None = PIPE,
|
||||||
|
stdout: int | IO[Any] | None = PIPE,
|
||||||
|
stderr: int | IO[Any] | None = PIPE,
|
||||||
|
cwd: StrOrBytesPath | None = None,
|
||||||
|
env: Mapping[str, str] | None = None,
|
||||||
|
startupinfo: Any = None,
|
||||||
|
creationflags: int = 0,
|
||||||
|
start_new_session: bool = False,
|
||||||
|
pass_fds: Sequence[int] = (),
|
||||||
|
user: str | int | None = None,
|
||||||
|
group: str | int | None = None,
|
||||||
|
extra_groups: Iterable[str | int] | None = None,
|
||||||
|
umask: int = -1,
|
||||||
|
) -> Process:
|
||||||
|
"""
|
||||||
|
Start an external command in a subprocess.
|
||||||
|
|
||||||
|
.. seealso:: :class:`subprocess.Popen`
|
||||||
|
|
||||||
|
:param command: either a string to pass to the shell, or an iterable of strings
|
||||||
|
containing the executable name or path and its arguments
|
||||||
|
:param stdin: one of :data:`subprocess.PIPE`, :data:`subprocess.DEVNULL`, a
|
||||||
|
file-like object, or ``None``
|
||||||
|
:param stdout: one of :data:`subprocess.PIPE`, :data:`subprocess.DEVNULL`,
|
||||||
|
a file-like object, or ``None``
|
||||||
|
:param stderr: one of :data:`subprocess.PIPE`, :data:`subprocess.DEVNULL`,
|
||||||
|
:data:`subprocess.STDOUT`, a file-like object, or ``None``
|
||||||
|
:param cwd: If not ``None``, the working directory is changed before executing
|
||||||
|
:param env: If env is not ``None``, it must be a mapping that defines the
|
||||||
|
environment variables for the new process
|
||||||
|
:param creationflags: flags that can be used to control the creation of the
|
||||||
|
subprocess (see :class:`subprocess.Popen` for the specifics)
|
||||||
|
:param startupinfo: an instance of :class:`subprocess.STARTUPINFO` that can be used
|
||||||
|
to specify process startup parameters (Windows only)
|
||||||
|
:param start_new_session: if ``true`` the setsid() system call will be made in the
|
||||||
|
child process prior to the execution of the subprocess. (POSIX only)
|
||||||
|
:param pass_fds: sequence of file descriptors to keep open between the parent and
|
||||||
|
child processes. (POSIX only)
|
||||||
|
:param user: effective user to run the process as (POSIX only)
|
||||||
|
:param group: effective group to run the process as (POSIX only)
|
||||||
|
:param extra_groups: supplementary groups to set in the subprocess (POSIX only)
|
||||||
|
:param umask: if not negative, this umask is applied in the child process before
|
||||||
|
running the given command (POSIX only)
|
||||||
|
:return: an asynchronous process object
|
||||||
|
|
||||||
|
"""
|
||||||
|
kwargs: dict[str, Any] = {}
|
||||||
|
if user is not None:
|
||||||
|
kwargs["user"] = user
|
||||||
|
|
||||||
|
if group is not None:
|
||||||
|
kwargs["group"] = group
|
||||||
|
|
||||||
|
if extra_groups is not None:
|
||||||
|
kwargs["extra_groups"] = extra_groups
|
||||||
|
|
||||||
|
if umask >= 0:
|
||||||
|
kwargs["umask"] = umask
|
||||||
|
|
||||||
|
return await get_async_backend().open_process(
|
||||||
|
command,
|
||||||
|
stdin=stdin,
|
||||||
|
stdout=stdout,
|
||||||
|
stderr=stderr,
|
||||||
|
cwd=cwd,
|
||||||
|
env=env,
|
||||||
|
startupinfo=startupinfo,
|
||||||
|
creationflags=creationflags,
|
||||||
|
start_new_session=start_new_session,
|
||||||
|
pass_fds=pass_fds,
|
||||||
|
**kwargs,
|
||||||
|
)
|
||||||
@@ -0,0 +1,778 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import math
|
||||||
|
import sys
|
||||||
|
from collections import deque
|
||||||
|
from collections.abc import Callable
|
||||||
|
from dataclasses import dataclass
|
||||||
|
from types import TracebackType
|
||||||
|
from typing import TypeVar
|
||||||
|
|
||||||
|
from ..lowlevel import checkpoint_if_cancelled
|
||||||
|
from ._eventloop import get_async_backend
|
||||||
|
from ._exceptions import BusyResourceError, NoEventLoopError
|
||||||
|
from ._tasks import CancelScope
|
||||||
|
from ._testing import TaskInfo, get_current_task
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import Self
|
||||||
|
else:
|
||||||
|
from typing_extensions import Self
|
||||||
|
|
||||||
|
T = TypeVar("T")
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True)
|
||||||
|
class EventStatistics:
|
||||||
|
"""
|
||||||
|
:ivar int tasks_waiting: number of tasks waiting on :meth:`~.Event.wait`
|
||||||
|
"""
|
||||||
|
|
||||||
|
tasks_waiting: int
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True)
|
||||||
|
class CapacityLimiterStatistics:
|
||||||
|
"""
|
||||||
|
:ivar int borrowed_tokens: number of tokens currently borrowed by tasks
|
||||||
|
:ivar float total_tokens: total number of available tokens
|
||||||
|
:ivar tuple borrowers: tasks or other objects currently holding tokens borrowed from
|
||||||
|
this limiter
|
||||||
|
:ivar int tasks_waiting: number of tasks waiting on
|
||||||
|
:meth:`~.CapacityLimiter.acquire` or
|
||||||
|
:meth:`~.CapacityLimiter.acquire_on_behalf_of`
|
||||||
|
"""
|
||||||
|
|
||||||
|
borrowed_tokens: int
|
||||||
|
total_tokens: float
|
||||||
|
borrowers: tuple[object, ...]
|
||||||
|
tasks_waiting: int
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True)
|
||||||
|
class LockStatistics:
|
||||||
|
"""
|
||||||
|
:ivar bool locked: flag indicating if this lock is locked or not
|
||||||
|
:ivar ~anyio.TaskInfo owner: task currently holding the lock (or ``None`` if the
|
||||||
|
lock is not held by any task)
|
||||||
|
:ivar int tasks_waiting: number of tasks waiting on :meth:`~.Lock.acquire`
|
||||||
|
"""
|
||||||
|
|
||||||
|
locked: bool
|
||||||
|
owner: TaskInfo | None
|
||||||
|
tasks_waiting: int
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True)
|
||||||
|
class ConditionStatistics:
|
||||||
|
"""
|
||||||
|
:ivar int tasks_waiting: number of tasks blocked on :meth:`~.Condition.wait`
|
||||||
|
:ivar ~anyio.LockStatistics lock_statistics: statistics of the underlying
|
||||||
|
:class:`~.Lock`
|
||||||
|
"""
|
||||||
|
|
||||||
|
tasks_waiting: int
|
||||||
|
lock_statistics: LockStatistics
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True)
|
||||||
|
class SemaphoreStatistics:
|
||||||
|
"""
|
||||||
|
:ivar int tasks_waiting: number of tasks waiting on :meth:`~.Semaphore.acquire`
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
tasks_waiting: int
|
||||||
|
|
||||||
|
|
||||||
|
class Event:
|
||||||
|
__slots__ = ("__weakref__",)
|
||||||
|
|
||||||
|
def __new__(cls) -> Event:
|
||||||
|
try:
|
||||||
|
return get_async_backend().create_event()
|
||||||
|
except NoEventLoopError:
|
||||||
|
return EventAdapter()
|
||||||
|
|
||||||
|
def set(self) -> None:
|
||||||
|
"""Set the flag, notifying all listeners."""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def is_set(self) -> bool:
|
||||||
|
"""Return ``True`` if the flag is set, ``False`` if not."""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
async def wait(self) -> None:
|
||||||
|
"""
|
||||||
|
Wait until the flag has been set.
|
||||||
|
|
||||||
|
If the flag has already been set when this method is called, it returns
|
||||||
|
immediately.
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def statistics(self) -> EventStatistics:
|
||||||
|
"""Return statistics about the current state of this event."""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
class EventAdapter(Event):
|
||||||
|
__slots__ = "_internal_event", "_is_set"
|
||||||
|
|
||||||
|
def __new__(cls) -> Self:
|
||||||
|
return object.__new__(cls)
|
||||||
|
|
||||||
|
def __init__(self) -> None:
|
||||||
|
self._internal_event: Event | None = None
|
||||||
|
self._is_set = False
|
||||||
|
|
||||||
|
@property
|
||||||
|
def _event(self) -> Event:
|
||||||
|
if self._internal_event is None:
|
||||||
|
self._internal_event = get_async_backend().create_event()
|
||||||
|
if self._is_set:
|
||||||
|
self._internal_event.set()
|
||||||
|
|
||||||
|
return self._internal_event
|
||||||
|
|
||||||
|
def set(self) -> None:
|
||||||
|
if self._internal_event is None:
|
||||||
|
self._is_set = True
|
||||||
|
else:
|
||||||
|
self._event.set()
|
||||||
|
|
||||||
|
def is_set(self) -> bool:
|
||||||
|
if self._internal_event is None:
|
||||||
|
return self._is_set
|
||||||
|
|
||||||
|
return self._internal_event.is_set()
|
||||||
|
|
||||||
|
async def wait(self) -> None:
|
||||||
|
await self._event.wait()
|
||||||
|
|
||||||
|
def statistics(self) -> EventStatistics:
|
||||||
|
if self._internal_event is None:
|
||||||
|
return EventStatistics(tasks_waiting=0)
|
||||||
|
|
||||||
|
return self._internal_event.statistics()
|
||||||
|
|
||||||
|
|
||||||
|
class Lock:
|
||||||
|
__slots__ = ("__weakref__",)
|
||||||
|
|
||||||
|
def __new__(cls, *, fast_acquire: bool = False) -> Lock:
|
||||||
|
try:
|
||||||
|
return get_async_backend().create_lock(fast_acquire=fast_acquire)
|
||||||
|
except NoEventLoopError:
|
||||||
|
return LockAdapter(fast_acquire=fast_acquire)
|
||||||
|
|
||||||
|
async def __aenter__(self) -> None:
|
||||||
|
await self.acquire()
|
||||||
|
|
||||||
|
async def __aexit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
self.release()
|
||||||
|
|
||||||
|
async def acquire(self) -> None:
|
||||||
|
"""Acquire the lock."""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def acquire_nowait(self) -> None:
|
||||||
|
"""
|
||||||
|
Acquire the lock, without blocking.
|
||||||
|
|
||||||
|
:raises ~anyio.WouldBlock: if the operation would block
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def release(self) -> None:
|
||||||
|
"""Release the lock."""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def locked(self) -> bool:
|
||||||
|
"""Return True if the lock is currently held."""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def statistics(self) -> LockStatistics:
|
||||||
|
"""
|
||||||
|
Return statistics about the current state of this lock.
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
class LockAdapter(Lock):
|
||||||
|
__slots__ = "_fast_acquire", "_internal_lock"
|
||||||
|
|
||||||
|
def __new__(cls, *, fast_acquire: bool = False) -> Self:
|
||||||
|
return object.__new__(cls)
|
||||||
|
|
||||||
|
def __init__(self, *, fast_acquire: bool = False):
|
||||||
|
self._internal_lock: Lock | None = None
|
||||||
|
self._fast_acquire = fast_acquire
|
||||||
|
|
||||||
|
@property
|
||||||
|
def _lock(self) -> Lock:
|
||||||
|
if self._internal_lock is None:
|
||||||
|
self._internal_lock = get_async_backend().create_lock(
|
||||||
|
fast_acquire=self._fast_acquire
|
||||||
|
)
|
||||||
|
|
||||||
|
return self._internal_lock
|
||||||
|
|
||||||
|
async def __aenter__(self) -> None:
|
||||||
|
await self._lock.acquire()
|
||||||
|
|
||||||
|
async def __aexit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
if self._internal_lock is not None:
|
||||||
|
self._internal_lock.release()
|
||||||
|
|
||||||
|
async def acquire(self) -> None:
|
||||||
|
"""Acquire the lock."""
|
||||||
|
await self._lock.acquire()
|
||||||
|
|
||||||
|
def acquire_nowait(self) -> None:
|
||||||
|
"""
|
||||||
|
Acquire the lock, without blocking.
|
||||||
|
|
||||||
|
:raises ~anyio.WouldBlock: if the operation would block
|
||||||
|
|
||||||
|
"""
|
||||||
|
self._lock.acquire_nowait()
|
||||||
|
|
||||||
|
def release(self) -> None:
|
||||||
|
"""Release the lock."""
|
||||||
|
self._lock.release()
|
||||||
|
|
||||||
|
def locked(self) -> bool:
|
||||||
|
"""Return True if the lock is currently held."""
|
||||||
|
return self._lock.locked()
|
||||||
|
|
||||||
|
def statistics(self) -> LockStatistics:
|
||||||
|
"""
|
||||||
|
Return statistics about the current state of this lock.
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
if self._internal_lock is None:
|
||||||
|
return LockStatistics(False, None, 0)
|
||||||
|
|
||||||
|
return self._internal_lock.statistics()
|
||||||
|
|
||||||
|
|
||||||
|
class Condition:
|
||||||
|
__slots__ = "__weakref__", "_lock", "_owner_task", "_waiters"
|
||||||
|
|
||||||
|
def __init__(self, lock: Lock | None = None):
|
||||||
|
self._owner_task: TaskInfo | None = None
|
||||||
|
self._lock = lock or Lock()
|
||||||
|
self._waiters: deque[Event] = deque()
|
||||||
|
|
||||||
|
async def __aenter__(self) -> None:
|
||||||
|
await self.acquire()
|
||||||
|
|
||||||
|
async def __aexit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
self.release()
|
||||||
|
|
||||||
|
def _check_acquired(self) -> None:
|
||||||
|
if self._owner_task != get_current_task():
|
||||||
|
raise RuntimeError("The current task is not holding the underlying lock")
|
||||||
|
|
||||||
|
async def acquire(self) -> None:
|
||||||
|
"""Acquire the underlying lock."""
|
||||||
|
await self._lock.acquire()
|
||||||
|
self._owner_task = get_current_task()
|
||||||
|
|
||||||
|
def acquire_nowait(self) -> None:
|
||||||
|
"""
|
||||||
|
Acquire the underlying lock, without blocking.
|
||||||
|
|
||||||
|
:raises ~anyio.WouldBlock: if the operation would block
|
||||||
|
|
||||||
|
"""
|
||||||
|
self._lock.acquire_nowait()
|
||||||
|
self._owner_task = get_current_task()
|
||||||
|
|
||||||
|
def release(self) -> None:
|
||||||
|
"""Release the underlying lock."""
|
||||||
|
self._lock.release()
|
||||||
|
|
||||||
|
def locked(self) -> bool:
|
||||||
|
"""Return True if the lock is set."""
|
||||||
|
return self._lock.locked()
|
||||||
|
|
||||||
|
def notify(self, n: int = 1) -> None:
|
||||||
|
"""Notify exactly n listeners."""
|
||||||
|
self._check_acquired()
|
||||||
|
for _ in range(n):
|
||||||
|
try:
|
||||||
|
event = self._waiters.popleft()
|
||||||
|
except IndexError:
|
||||||
|
break
|
||||||
|
|
||||||
|
event.set()
|
||||||
|
|
||||||
|
def notify_all(self) -> None:
|
||||||
|
"""Notify all the listeners."""
|
||||||
|
self._check_acquired()
|
||||||
|
for event in self._waiters:
|
||||||
|
event.set()
|
||||||
|
|
||||||
|
self._waiters.clear()
|
||||||
|
|
||||||
|
async def wait(self) -> None:
|
||||||
|
"""Wait for a notification."""
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
self._check_acquired()
|
||||||
|
event = Event()
|
||||||
|
self._waiters.append(event)
|
||||||
|
self.release()
|
||||||
|
try:
|
||||||
|
await event.wait()
|
||||||
|
except BaseException:
|
||||||
|
if not event.is_set():
|
||||||
|
self._waiters.remove(event)
|
||||||
|
elif self._waiters:
|
||||||
|
# This task was notified by could not act on it, so pass
|
||||||
|
# it on to the next task
|
||||||
|
self._waiters.popleft().set()
|
||||||
|
|
||||||
|
raise
|
||||||
|
finally:
|
||||||
|
with CancelScope(shield=True):
|
||||||
|
await self.acquire()
|
||||||
|
|
||||||
|
async def wait_for(self, predicate: Callable[[], T]) -> T:
|
||||||
|
"""
|
||||||
|
Wait until a predicate becomes true.
|
||||||
|
|
||||||
|
:param predicate: a callable that returns a truthy value when the condition is
|
||||||
|
met
|
||||||
|
:return: the result of the predicate
|
||||||
|
|
||||||
|
.. versionadded:: 4.11.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
while not (result := predicate()):
|
||||||
|
await self.wait()
|
||||||
|
|
||||||
|
return result
|
||||||
|
|
||||||
|
def statistics(self) -> ConditionStatistics:
|
||||||
|
"""
|
||||||
|
Return statistics about the current state of this condition.
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
"""
|
||||||
|
return ConditionStatistics(len(self._waiters), self._lock.statistics())
|
||||||
|
|
||||||
|
|
||||||
|
class Semaphore:
|
||||||
|
__slots__ = "__weakref__", "_fast_acquire"
|
||||||
|
|
||||||
|
def __new__(
|
||||||
|
cls,
|
||||||
|
initial_value: int,
|
||||||
|
*,
|
||||||
|
max_value: int | None = None,
|
||||||
|
fast_acquire: bool = False,
|
||||||
|
) -> Semaphore:
|
||||||
|
try:
|
||||||
|
return get_async_backend().create_semaphore(
|
||||||
|
initial_value, max_value=max_value, fast_acquire=fast_acquire
|
||||||
|
)
|
||||||
|
except NoEventLoopError:
|
||||||
|
return SemaphoreAdapter(initial_value, max_value=max_value)
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
initial_value: int,
|
||||||
|
*,
|
||||||
|
max_value: int | None = None,
|
||||||
|
fast_acquire: bool = False,
|
||||||
|
):
|
||||||
|
if not isinstance(initial_value, int):
|
||||||
|
raise TypeError("initial_value must be an integer")
|
||||||
|
if initial_value < 0:
|
||||||
|
raise ValueError("initial_value must be >= 0")
|
||||||
|
if max_value is not None:
|
||||||
|
if not isinstance(max_value, int):
|
||||||
|
raise TypeError("max_value must be an integer or None")
|
||||||
|
if max_value < initial_value:
|
||||||
|
raise ValueError(
|
||||||
|
"max_value must be equal to or higher than initial_value"
|
||||||
|
)
|
||||||
|
|
||||||
|
self._fast_acquire = fast_acquire
|
||||||
|
|
||||||
|
async def __aenter__(self) -> Self:
|
||||||
|
await self.acquire()
|
||||||
|
return self
|
||||||
|
|
||||||
|
async def __aexit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
self.release()
|
||||||
|
|
||||||
|
async def acquire(self) -> None:
|
||||||
|
"""Decrement the semaphore value, blocking if necessary."""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def acquire_nowait(self) -> None:
|
||||||
|
"""
|
||||||
|
Acquire the underlying lock, without blocking.
|
||||||
|
|
||||||
|
:raises ~anyio.WouldBlock: if the operation would block
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def release(self) -> None:
|
||||||
|
"""Increment the semaphore value."""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@property
|
||||||
|
def value(self) -> int:
|
||||||
|
"""The current value of the semaphore."""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@property
|
||||||
|
def max_value(self) -> int | None:
|
||||||
|
"""The maximum value of the semaphore."""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def statistics(self) -> SemaphoreStatistics:
|
||||||
|
"""
|
||||||
|
Return statistics about the current state of this semaphore.
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
class SemaphoreAdapter(Semaphore):
|
||||||
|
__slots__ = "_initial_value", "_internal_semaphore", "_max_value"
|
||||||
|
|
||||||
|
def __new__(
|
||||||
|
cls,
|
||||||
|
initial_value: int,
|
||||||
|
*,
|
||||||
|
max_value: int | None = None,
|
||||||
|
fast_acquire: bool = False,
|
||||||
|
) -> Self:
|
||||||
|
return object.__new__(cls)
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
initial_value: int,
|
||||||
|
*,
|
||||||
|
max_value: int | None = None,
|
||||||
|
fast_acquire: bool = False,
|
||||||
|
) -> None:
|
||||||
|
super().__init__(initial_value, max_value=max_value, fast_acquire=fast_acquire)
|
||||||
|
self._internal_semaphore: Semaphore | None = None
|
||||||
|
self._initial_value = initial_value
|
||||||
|
self._max_value = max_value
|
||||||
|
|
||||||
|
@property
|
||||||
|
def _semaphore(self) -> Semaphore:
|
||||||
|
if self._internal_semaphore is None:
|
||||||
|
self._internal_semaphore = get_async_backend().create_semaphore(
|
||||||
|
self._initial_value, max_value=self._max_value
|
||||||
|
)
|
||||||
|
|
||||||
|
return self._internal_semaphore
|
||||||
|
|
||||||
|
async def acquire(self) -> None:
|
||||||
|
await self._semaphore.acquire()
|
||||||
|
|
||||||
|
def acquire_nowait(self) -> None:
|
||||||
|
self._semaphore.acquire_nowait()
|
||||||
|
|
||||||
|
def release(self) -> None:
|
||||||
|
self._semaphore.release()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def value(self) -> int:
|
||||||
|
if self._internal_semaphore is None:
|
||||||
|
return self._initial_value
|
||||||
|
|
||||||
|
return self._semaphore.value
|
||||||
|
|
||||||
|
@property
|
||||||
|
def max_value(self) -> int | None:
|
||||||
|
return self._max_value
|
||||||
|
|
||||||
|
def statistics(self) -> SemaphoreStatistics:
|
||||||
|
if self._internal_semaphore is None:
|
||||||
|
return SemaphoreStatistics(tasks_waiting=0)
|
||||||
|
|
||||||
|
return self._semaphore.statistics()
|
||||||
|
|
||||||
|
|
||||||
|
class CapacityLimiter:
|
||||||
|
__slots__ = ("__weakref__",)
|
||||||
|
|
||||||
|
def __new__(cls, total_tokens: float) -> CapacityLimiter:
|
||||||
|
try:
|
||||||
|
return get_async_backend().create_capacity_limiter(total_tokens)
|
||||||
|
except NoEventLoopError:
|
||||||
|
return CapacityLimiterAdapter(total_tokens)
|
||||||
|
|
||||||
|
async def __aenter__(self) -> None:
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
async def __aexit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@property
|
||||||
|
def total_tokens(self) -> float:
|
||||||
|
"""
|
||||||
|
The total number of tokens available for borrowing.
|
||||||
|
|
||||||
|
This is a read-write property. If the total number of tokens is increased, the
|
||||||
|
proportionate number of tasks waiting on this limiter will be granted their
|
||||||
|
tokens.
|
||||||
|
|
||||||
|
.. versionchanged:: 3.0
|
||||||
|
The property is now writable.
|
||||||
|
.. versionchanged:: 4.12
|
||||||
|
The value can now be set to 0.
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@total_tokens.setter
|
||||||
|
def total_tokens(self, value: float) -> None:
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@property
|
||||||
|
def borrowed_tokens(self) -> int:
|
||||||
|
"""The number of tokens that have currently been borrowed."""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@property
|
||||||
|
def available_tokens(self) -> float:
|
||||||
|
"""The number of tokens currently available to be borrowed"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def acquire_nowait(self) -> None:
|
||||||
|
"""
|
||||||
|
Acquire a token for the current task without waiting for one to become
|
||||||
|
available.
|
||||||
|
|
||||||
|
:raises ~anyio.WouldBlock: if there are no tokens available for borrowing
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def acquire_on_behalf_of_nowait(self, borrower: object) -> None:
|
||||||
|
"""
|
||||||
|
Acquire a token without waiting for one to become available.
|
||||||
|
|
||||||
|
:param borrower: the entity borrowing a token
|
||||||
|
:raises ~anyio.WouldBlock: if there are no tokens available for borrowing
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
async def acquire(self) -> None:
|
||||||
|
"""
|
||||||
|
Acquire a token for the current task, waiting if necessary for one to become
|
||||||
|
available.
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
async def acquire_on_behalf_of(self, borrower: object) -> None:
|
||||||
|
"""
|
||||||
|
Acquire a token, waiting if necessary for one to become available.
|
||||||
|
|
||||||
|
:param borrower: the entity borrowing a token
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def release(self) -> None:
|
||||||
|
"""
|
||||||
|
Release the token held by the current task.
|
||||||
|
|
||||||
|
:raises RuntimeError: if the current task has not borrowed a token from this
|
||||||
|
limiter.
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def release_on_behalf_of(self, borrower: object) -> None:
|
||||||
|
"""
|
||||||
|
Release the token held by the given borrower.
|
||||||
|
|
||||||
|
:raises RuntimeError: if the borrower has not borrowed a token from this
|
||||||
|
limiter.
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def statistics(self) -> CapacityLimiterStatistics:
|
||||||
|
"""
|
||||||
|
Return statistics about the current state of this limiter.
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
class CapacityLimiterAdapter(CapacityLimiter):
|
||||||
|
__slots__ = "_internal_limiter", "_total_tokens"
|
||||||
|
|
||||||
|
def __new__(cls, total_tokens: float) -> Self:
|
||||||
|
return object.__new__(cls)
|
||||||
|
|
||||||
|
def __init__(self, total_tokens: float) -> None:
|
||||||
|
self._internal_limiter: CapacityLimiter | None = None
|
||||||
|
self.total_tokens = total_tokens
|
||||||
|
|
||||||
|
@property
|
||||||
|
def _limiter(self) -> CapacityLimiter:
|
||||||
|
if self._internal_limiter is None:
|
||||||
|
self._internal_limiter = get_async_backend().create_capacity_limiter(
|
||||||
|
self._total_tokens
|
||||||
|
)
|
||||||
|
|
||||||
|
return self._internal_limiter
|
||||||
|
|
||||||
|
async def __aenter__(self) -> None:
|
||||||
|
await self._limiter.__aenter__()
|
||||||
|
|
||||||
|
async def __aexit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
return await self._limiter.__aexit__(exc_type, exc_val, exc_tb)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def total_tokens(self) -> float:
|
||||||
|
if self._internal_limiter is None:
|
||||||
|
return self._total_tokens
|
||||||
|
|
||||||
|
return self._internal_limiter.total_tokens
|
||||||
|
|
||||||
|
@total_tokens.setter
|
||||||
|
def total_tokens(self, value: float) -> None:
|
||||||
|
if not isinstance(value, int) and not math.isinf(value):
|
||||||
|
raise TypeError("total_tokens must be an int or math.inf")
|
||||||
|
elif value < 0:
|
||||||
|
raise ValueError("total_tokens must be >= 0")
|
||||||
|
|
||||||
|
if self._internal_limiter is None:
|
||||||
|
self._total_tokens = value
|
||||||
|
return
|
||||||
|
|
||||||
|
self._limiter.total_tokens = value
|
||||||
|
|
||||||
|
@property
|
||||||
|
def borrowed_tokens(self) -> int:
|
||||||
|
if self._internal_limiter is None:
|
||||||
|
return 0
|
||||||
|
|
||||||
|
return self._internal_limiter.borrowed_tokens
|
||||||
|
|
||||||
|
@property
|
||||||
|
def available_tokens(self) -> float:
|
||||||
|
if self._internal_limiter is None:
|
||||||
|
return self._total_tokens
|
||||||
|
|
||||||
|
return self._internal_limiter.available_tokens
|
||||||
|
|
||||||
|
def acquire_nowait(self) -> None:
|
||||||
|
self._limiter.acquire_nowait()
|
||||||
|
|
||||||
|
def acquire_on_behalf_of_nowait(self, borrower: object) -> None:
|
||||||
|
self._limiter.acquire_on_behalf_of_nowait(borrower)
|
||||||
|
|
||||||
|
async def acquire(self) -> None:
|
||||||
|
await self._limiter.acquire()
|
||||||
|
|
||||||
|
async def acquire_on_behalf_of(self, borrower: object) -> None:
|
||||||
|
await self._limiter.acquire_on_behalf_of(borrower)
|
||||||
|
|
||||||
|
def release(self) -> None:
|
||||||
|
self._limiter.release()
|
||||||
|
|
||||||
|
def release_on_behalf_of(self, borrower: object) -> None:
|
||||||
|
self._limiter.release_on_behalf_of(borrower)
|
||||||
|
|
||||||
|
def statistics(self) -> CapacityLimiterStatistics:
|
||||||
|
if self._internal_limiter is None:
|
||||||
|
return CapacityLimiterStatistics(
|
||||||
|
borrowed_tokens=0,
|
||||||
|
total_tokens=self.total_tokens,
|
||||||
|
borrowers=(),
|
||||||
|
tasks_waiting=0,
|
||||||
|
)
|
||||||
|
|
||||||
|
return self._internal_limiter.statistics()
|
||||||
|
|
||||||
|
|
||||||
|
class ResourceGuard:
|
||||||
|
"""
|
||||||
|
A context manager for ensuring that a resource is only used by a single task at a
|
||||||
|
time.
|
||||||
|
|
||||||
|
Entering this context manager while the previous has not exited it yet will trigger
|
||||||
|
:exc:`BusyResourceError`.
|
||||||
|
|
||||||
|
:param action: the action to guard against (visible in the :exc:`BusyResourceError`
|
||||||
|
when triggered, e.g. "Another task is already {action} this resource")
|
||||||
|
|
||||||
|
.. versionadded:: 4.1
|
||||||
|
"""
|
||||||
|
|
||||||
|
__slots__ = "__weakref__", "_guarded", "action"
|
||||||
|
|
||||||
|
def __init__(self, action: str = "using"):
|
||||||
|
self.action: str = action
|
||||||
|
self._guarded = False
|
||||||
|
|
||||||
|
def __enter__(self) -> None:
|
||||||
|
if self._guarded:
|
||||||
|
raise BusyResourceError(self.action)
|
||||||
|
|
||||||
|
self._guarded = True
|
||||||
|
|
||||||
|
def __exit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
self._guarded = False
|
||||||
@@ -0,0 +1,464 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import math
|
||||||
|
import sys
|
||||||
|
from collections.abc import (
|
||||||
|
Coroutine,
|
||||||
|
Generator,
|
||||||
|
)
|
||||||
|
from contextlib import contextmanager
|
||||||
|
from enum import Enum, auto
|
||||||
|
from inspect import iscoroutine
|
||||||
|
from types import TracebackType
|
||||||
|
from typing import Any, Generic, final
|
||||||
|
|
||||||
|
from ..abc import TaskGroup, TaskStatus
|
||||||
|
from ._eventloop import get_async_backend, get_cancelled_exc_class
|
||||||
|
from ._exceptions import TaskCancelled, TaskFailed, TaskNotFinished
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 13):
|
||||||
|
from typing import TypeVar
|
||||||
|
else:
|
||||||
|
from typing_extensions import TypeVar
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import Never, Self, TypeVarTuple
|
||||||
|
else:
|
||||||
|
from typing_extensions import Never, Self, TypeVarTuple
|
||||||
|
|
||||||
|
T = TypeVar("T")
|
||||||
|
T_co = TypeVar("T_co", covariant=True)
|
||||||
|
T_startval_co = TypeVar("T_startval_co", covariant=True, default=Never)
|
||||||
|
PosArgsT = TypeVarTuple("PosArgsT")
|
||||||
|
|
||||||
|
|
||||||
|
class _IgnoredTaskStatus(TaskStatus[object]):
|
||||||
|
def started(self, value: object = None) -> None:
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
TASK_STATUS_IGNORED = _IgnoredTaskStatus()
|
||||||
|
|
||||||
|
|
||||||
|
class CancelScope:
|
||||||
|
"""
|
||||||
|
Wraps a unit of work that can be made separately cancellable.
|
||||||
|
|
||||||
|
:param deadline: The time (clock value) when this scope is cancelled automatically
|
||||||
|
:param shield: ``True`` to shield the cancel scope from external cancellation
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
"""
|
||||||
|
|
||||||
|
__slots__ = ("__weakref__",)
|
||||||
|
|
||||||
|
def __new__(
|
||||||
|
cls, *, deadline: float = math.inf, shield: bool = False
|
||||||
|
) -> CancelScope:
|
||||||
|
return get_async_backend().create_cancel_scope(shield=shield, deadline=deadline)
|
||||||
|
|
||||||
|
def cancel(self, reason: str | None = None) -> None:
|
||||||
|
"""
|
||||||
|
Cancel this scope immediately.
|
||||||
|
|
||||||
|
:param reason: a message describing the reason for the cancellation
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@property
|
||||||
|
def deadline(self) -> float:
|
||||||
|
"""
|
||||||
|
The time (clock value) when this scope is cancelled automatically.
|
||||||
|
|
||||||
|
Will be ``float('inf')`` if no timeout has been set.
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@deadline.setter
|
||||||
|
def deadline(self, value: float) -> None:
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@property
|
||||||
|
def cancel_called(self) -> bool:
|
||||||
|
"""``True`` if :meth:`cancel` has been called."""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@property
|
||||||
|
def cancelled_caught(self) -> bool:
|
||||||
|
"""
|
||||||
|
``True`` if this scope suppressed a cancellation exception it itself raised.
|
||||||
|
|
||||||
|
This is typically used to check if any work was interrupted, or to see if the
|
||||||
|
scope was cancelled due to its deadline being reached. The value will, however,
|
||||||
|
only be ``True`` if the cancellation was triggered by the scope itself (and not
|
||||||
|
an outer scope).
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@property
|
||||||
|
def shield(self) -> bool:
|
||||||
|
"""
|
||||||
|
``True`` if this scope is shielded from external cancellation.
|
||||||
|
|
||||||
|
While a scope is shielded, it will not receive cancellations from outside.
|
||||||
|
|
||||||
|
"""
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
@shield.setter
|
||||||
|
def shield(self, value: bool) -> None:
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def __enter__(self) -> Self:
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def __exit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> bool:
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
@contextmanager
|
||||||
|
def fail_at(
|
||||||
|
deadline: float | None, shield: bool = False, reason: str | None = None
|
||||||
|
) -> Generator[CancelScope, None, None]:
|
||||||
|
"""
|
||||||
|
Create a context manager which raises a :class:`TimeoutError` if the code in the
|
||||||
|
enclosing context does not finish by the given deadline.
|
||||||
|
|
||||||
|
:param deadline: the deadline before raising the exception, or
|
||||||
|
``None`` to disable the timeout
|
||||||
|
:param shield: ``True`` to shield the cancel scope from external cancellation
|
||||||
|
:param reason: explanation for timeout to add to the message of a raised `TimeoutError`
|
||||||
|
:return: a context manager that yields a cancel scope
|
||||||
|
:rtype: :class:`~typing.ContextManager`\\[:class:`~anyio.CancelScope`\\]
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
.. versionadded:: 4.15.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
current_time = get_async_backend().current_time
|
||||||
|
effective_deadline = math.inf if deadline is None else deadline
|
||||||
|
with get_async_backend().create_cancel_scope(
|
||||||
|
deadline=effective_deadline, shield=shield
|
||||||
|
) as cancel_scope:
|
||||||
|
yield cancel_scope
|
||||||
|
|
||||||
|
if cancel_scope.cancelled_caught and current_time() >= cancel_scope.deadline:
|
||||||
|
raise TimeoutError(reason) if reason else TimeoutError
|
||||||
|
|
||||||
|
|
||||||
|
@contextmanager
|
||||||
|
def fail_after(
|
||||||
|
delay: float | None, shield: bool = False, reason: str | None = None
|
||||||
|
) -> Generator[CancelScope, None, None]:
|
||||||
|
"""
|
||||||
|
Create a context manager which raises a :class:`TimeoutError` if the code in the
|
||||||
|
enclosing context block does not finish in time.
|
||||||
|
|
||||||
|
:param delay: maximum allowed time (in seconds) before raising the exception, or
|
||||||
|
``None`` to disable the timeout
|
||||||
|
:param shield: ``True`` to shield the cancel scope from external cancellation
|
||||||
|
:param reason: explanation for timeout to add to the message of a raised `TimeoutError`
|
||||||
|
:return: a context manager that yields a cancel scope
|
||||||
|
:rtype: :class:`~typing.ContextManager`\\[:class:`~anyio.CancelScope`\\]
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
"""
|
||||||
|
current_time = get_async_backend().current_time
|
||||||
|
deadline = (current_time() + delay) if delay is not None else math.inf
|
||||||
|
with fail_at(deadline, shield=shield, reason=reason) as scope:
|
||||||
|
yield scope
|
||||||
|
|
||||||
|
|
||||||
|
def move_on_at(deadline: float | None, shield: bool = False) -> CancelScope:
|
||||||
|
"""
|
||||||
|
Create a cancel scope with a deadline that expires after the given delay.
|
||||||
|
|
||||||
|
:param deadline: the deadline before exiting the context block, or
|
||||||
|
``None`` to disable the timeout
|
||||||
|
:param shield: ``True`` to shield the cancel scope from external cancellation
|
||||||
|
:return: a cancel scope
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
.. versionadded:: 4.15.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
return get_async_backend().create_cancel_scope(
|
||||||
|
deadline=deadline if deadline is not None else math.inf, shield=shield
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def move_on_after(delay: float | None, shield: bool = False) -> CancelScope:
|
||||||
|
"""
|
||||||
|
Create a cancel scope with a deadline that expires after the given delay.
|
||||||
|
|
||||||
|
:param delay: maximum allowed time (in seconds) before exiting the context block, or
|
||||||
|
``None`` to disable the timeout
|
||||||
|
:param shield: ``True`` to shield the cancel scope from external cancellation
|
||||||
|
:return: a cancel scope
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
.. note:: Unlike with :func:`fail_after`, the timer starts when this function is
|
||||||
|
called, not when the context manager is entered. This will be changed in v5.0.
|
||||||
|
|
||||||
|
"""
|
||||||
|
deadline = (
|
||||||
|
(get_async_backend().current_time() + delay) if delay is not None else math.inf
|
||||||
|
)
|
||||||
|
return get_async_backend().create_cancel_scope(deadline=deadline, shield=shield)
|
||||||
|
|
||||||
|
|
||||||
|
def current_effective_deadline() -> float:
|
||||||
|
"""
|
||||||
|
Return the nearest deadline among all the cancel scopes effective for the current
|
||||||
|
task.
|
||||||
|
|
||||||
|
:return: a clock value from the event loop's internal clock (or ``float('inf')`` if
|
||||||
|
there is no deadline in effect, or ``float('-inf')`` if the current scope has
|
||||||
|
been cancelled)
|
||||||
|
:rtype: float
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
"""
|
||||||
|
return get_async_backend().current_effective_deadline()
|
||||||
|
|
||||||
|
|
||||||
|
def create_task_group() -> TaskGroup:
|
||||||
|
"""
|
||||||
|
Create a task group.
|
||||||
|
|
||||||
|
:return: a task group
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
"""
|
||||||
|
return get_async_backend().create_task_group()
|
||||||
|
|
||||||
|
|
||||||
|
@final
|
||||||
|
class TaskHandle(Generic[T_co, T_startval_co]):
|
||||||
|
"""
|
||||||
|
Returned from the task-spawning methods of :class:`TaskGroup`. Can be awaited on to
|
||||||
|
get the return value of the task (or the raised exception). If the task was
|
||||||
|
terminated by a :exc:`BaseException`, :exc:`TaskFailed` will be raised (or its
|
||||||
|
subclass :exc:`TaskCancelled` if the task was cancelled).
|
||||||
|
|
||||||
|
.. versionadded:: 4.14.0
|
||||||
|
"""
|
||||||
|
|
||||||
|
class Status(Enum):
|
||||||
|
"""
|
||||||
|
The status of a task handle.
|
||||||
|
|
||||||
|
.. attribute:: PENDING
|
||||||
|
|
||||||
|
The task has not finished yet.
|
||||||
|
.. attribute:: FINISHED
|
||||||
|
|
||||||
|
The task has finished with a return value.
|
||||||
|
.. attribute:: CANCELLING
|
||||||
|
|
||||||
|
The task has been cancelled but has not finished yet.
|
||||||
|
.. attribute:: CANCELLED
|
||||||
|
|
||||||
|
The task was cancelled and has finished since.
|
||||||
|
.. attribute:: FAILED
|
||||||
|
|
||||||
|
The task raised an exception.
|
||||||
|
"""
|
||||||
|
|
||||||
|
PENDING = auto()
|
||||||
|
FINISHED = auto()
|
||||||
|
CANCELLING = auto()
|
||||||
|
CANCELLED = auto()
|
||||||
|
FAILED = auto()
|
||||||
|
|
||||||
|
__slots__ = (
|
||||||
|
"__weakref__",
|
||||||
|
"_cancel_scope",
|
||||||
|
"_coro",
|
||||||
|
"_exception",
|
||||||
|
"_finished_event",
|
||||||
|
"_name",
|
||||||
|
"_return_value",
|
||||||
|
"_start_value",
|
||||||
|
)
|
||||||
|
|
||||||
|
_return_value: T_co
|
||||||
|
_start_value: T_startval_co
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
coro: Coroutine[Any, Any, T_co],
|
||||||
|
name: object,
|
||||||
|
cancel_scope: CancelScope | None = None,
|
||||||
|
) -> None:
|
||||||
|
from ._synchronization import Event
|
||||||
|
|
||||||
|
self._coro = coro
|
||||||
|
self._cancel_scope = cancel_scope if cancel_scope is not None else CancelScope()
|
||||||
|
self._finished_event = Event()
|
||||||
|
self._exception: BaseException | None = None
|
||||||
|
|
||||||
|
if name is not None:
|
||||||
|
self._name = str(name)
|
||||||
|
elif iscoroutine(coro):
|
||||||
|
self._name = coro.__qualname__
|
||||||
|
else:
|
||||||
|
self._name = str(coro) # coroutine-like object (e.g. asend() objects)
|
||||||
|
|
||||||
|
async def _run_coro(self) -> None:
|
||||||
|
__tracebackhide__ = True
|
||||||
|
|
||||||
|
with self._cancel_scope:
|
||||||
|
try:
|
||||||
|
retval = await self._coro
|
||||||
|
except BaseException as exc:
|
||||||
|
self._exception = exc
|
||||||
|
raise
|
||||||
|
else:
|
||||||
|
self._return_value = retval
|
||||||
|
finally:
|
||||||
|
self._finished_event.set()
|
||||||
|
del self # Break the reference cycle
|
||||||
|
|
||||||
|
def cancel(self) -> None:
|
||||||
|
"""
|
||||||
|
Set the task to a cancelled state.
|
||||||
|
|
||||||
|
This will interrupt any interruptible asynchronous operation, and will cause
|
||||||
|
any further awaits on this task to get immediately cancelled, unless done in
|
||||||
|
a shielded cancel scope.
|
||||||
|
|
||||||
|
If the task has already finished, this method has no effect.
|
||||||
|
"""
|
||||||
|
if not self._finished_event.is_set():
|
||||||
|
self._cancel_scope.cancel()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def coro(self) -> Coroutine[Any, Any, T_co]:
|
||||||
|
"""
|
||||||
|
The coroutine object that was passed to one of the task-spawning methods in
|
||||||
|
:class:`TaskGroup`.
|
||||||
|
"""
|
||||||
|
return self._coro
|
||||||
|
|
||||||
|
@property
|
||||||
|
def status(self) -> TaskHandle.Status:
|
||||||
|
"""
|
||||||
|
The current status of the task.
|
||||||
|
|
||||||
|
Every task starts in the :attr:`~TaskHandle.Status.PENDING` state.
|
||||||
|
If a task is cancelled while in this state, it will transition to the
|
||||||
|
:attr:`~TaskHandle.Status.CANCELLING` state. When the task finishes, it will
|
||||||
|
transition to one of the three final states (
|
||||||
|
:attr:`~TaskHandle.Status.FINISHED`, :attr:`~TaskHandle.Status.FAILED`, or
|
||||||
|
:attr:`~TaskHandle.Status.CANCELLING`) depending on the exception the task
|
||||||
|
raised, if any. No other status transitions will happen.
|
||||||
|
"""
|
||||||
|
if not self._finished_event.is_set():
|
||||||
|
if self._cancel_scope.cancel_called:
|
||||||
|
return TaskHandle.Status.CANCELLING
|
||||||
|
else:
|
||||||
|
return TaskHandle.Status.PENDING
|
||||||
|
elif self._exception is not None:
|
||||||
|
if isinstance(self._exception, get_cancelled_exc_class()):
|
||||||
|
return TaskHandle.Status.CANCELLED
|
||||||
|
else:
|
||||||
|
return TaskHandle.Status.FAILED
|
||||||
|
else:
|
||||||
|
return TaskHandle.Status.FINISHED
|
||||||
|
|
||||||
|
@property
|
||||||
|
def name(self) -> str:
|
||||||
|
"""The name of the task."""
|
||||||
|
return self._name
|
||||||
|
|
||||||
|
@property
|
||||||
|
def exception(self) -> BaseException | None:
|
||||||
|
"""
|
||||||
|
The exception raised by the task, or ``None`` if it finished without raising.
|
||||||
|
|
||||||
|
:raises TaskNotFinished: if the task has not finished yet
|
||||||
|
:raises TaskCancelled: if the task was cancelled
|
||||||
|
|
||||||
|
"""
|
||||||
|
match self.status:
|
||||||
|
case TaskHandle.Status.PENDING:
|
||||||
|
raise TaskNotFinished("the task has not finished yet")
|
||||||
|
case TaskHandle.Status.FINISHED:
|
||||||
|
return None
|
||||||
|
case TaskHandle.Status.CANCELLING:
|
||||||
|
raise TaskCancelled("the task was cancelled")
|
||||||
|
case TaskHandle.Status.CANCELLED:
|
||||||
|
raise TaskCancelled("the task was cancelled") from self._exception
|
||||||
|
case TaskHandle.Status.FAILED:
|
||||||
|
return self._exception
|
||||||
|
|
||||||
|
@property
|
||||||
|
def return_value(self) -> T_co:
|
||||||
|
"""
|
||||||
|
The return value of the task.
|
||||||
|
|
||||||
|
:raises TaskNotFinished: if the task has not finished yet
|
||||||
|
:raises TaskCancelled: if the task was cancelled
|
||||||
|
:raises TaskFailed: if the task raised an exception
|
||||||
|
|
||||||
|
"""
|
||||||
|
match self.status:
|
||||||
|
case TaskHandle.Status.PENDING:
|
||||||
|
raise TaskNotFinished("the task has not finished yet")
|
||||||
|
case TaskHandle.Status.FINISHED:
|
||||||
|
return self._return_value
|
||||||
|
case TaskHandle.Status.CANCELLING:
|
||||||
|
raise TaskCancelled("the task was cancelled")
|
||||||
|
case TaskHandle.Status.CANCELLED:
|
||||||
|
raise TaskCancelled("the task was cancelled") from self._exception
|
||||||
|
case TaskHandle.Status.FAILED:
|
||||||
|
raise TaskFailed("the task raised an exception") from self._exception
|
||||||
|
|
||||||
|
@property
|
||||||
|
def start_value(self) -> T_startval_co:
|
||||||
|
"""
|
||||||
|
The value passed to :meth:`task_status.started() <.abc.TaskStatus.started>`,
|
||||||
|
|
||||||
|
:raises RuntimeError: if the task was not started with :meth:`TaskGroup.start()
|
||||||
|
<.abc.TaskGroup.start>`
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
return self._start_value
|
||||||
|
except AttributeError:
|
||||||
|
raise RuntimeError(
|
||||||
|
"the task was not started with TaskGroup.start()"
|
||||||
|
) from None
|
||||||
|
|
||||||
|
async def wait(self) -> None:
|
||||||
|
"""
|
||||||
|
Wait for the task to finish.
|
||||||
|
|
||||||
|
This method will return as soon as the task has finished, no matter how it
|
||||||
|
happened.
|
||||||
|
"""
|
||||||
|
await self._finished_event.wait()
|
||||||
|
|
||||||
|
def __await__(self) -> Generator[Any, Any, T_co]:
|
||||||
|
yield from self._finished_event.wait().__await__()
|
||||||
|
return self.return_value
|
||||||
|
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
return (
|
||||||
|
f"<{self.__class__.__name__} {self.status.name.lower()} "
|
||||||
|
f"name={self._name!r} coro={self._coro!r}>"
|
||||||
|
)
|
||||||
@@ -0,0 +1,615 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
import tempfile
|
||||||
|
from collections.abc import Iterable
|
||||||
|
from io import BytesIO, TextIOWrapper
|
||||||
|
from types import TracebackType
|
||||||
|
from typing import (
|
||||||
|
TYPE_CHECKING,
|
||||||
|
Any,
|
||||||
|
AnyStr,
|
||||||
|
Generic,
|
||||||
|
overload,
|
||||||
|
)
|
||||||
|
|
||||||
|
from .. import to_thread
|
||||||
|
from .._core._fileio import AsyncFile
|
||||||
|
from ..lowlevel import checkpoint_if_cancelled
|
||||||
|
from ._tasks import CancelScope
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
from _typeshed import OpenBinaryMode, OpenTextMode, ReadableBuffer, WriteableBuffer
|
||||||
|
|
||||||
|
|
||||||
|
class TemporaryFile(Generic[AnyStr]):
|
||||||
|
"""
|
||||||
|
An asynchronous temporary file that is automatically created and cleaned up.
|
||||||
|
|
||||||
|
This class provides an asynchronous context manager interface to a temporary file.
|
||||||
|
The file is created using Python's standard `tempfile.TemporaryFile` function in a
|
||||||
|
background thread, and is wrapped as an asynchronous file using `AsyncFile`.
|
||||||
|
|
||||||
|
:param mode: The mode in which the file is opened. Defaults to "w+b".
|
||||||
|
:param buffering: The buffering policy (-1 means the default buffering).
|
||||||
|
:param encoding: The encoding used to decode or encode the file. Only applicable in
|
||||||
|
text mode.
|
||||||
|
:param newline: Controls how universal newlines mode works (only applicable in text
|
||||||
|
mode).
|
||||||
|
:param suffix: The suffix for the temporary file name.
|
||||||
|
:param prefix: The prefix for the temporary file name.
|
||||||
|
:param dir: The directory in which the temporary file is created.
|
||||||
|
:param errors: The error handling scheme used for encoding/decoding errors.
|
||||||
|
"""
|
||||||
|
|
||||||
|
_async_file: AsyncFile[AnyStr]
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def __init__(
|
||||||
|
self: TemporaryFile[bytes],
|
||||||
|
mode: OpenBinaryMode = ...,
|
||||||
|
buffering: int = ...,
|
||||||
|
encoding: str | None = ...,
|
||||||
|
newline: str | None = ...,
|
||||||
|
suffix: str | None = ...,
|
||||||
|
prefix: str | None = ...,
|
||||||
|
dir: str | None = ...,
|
||||||
|
*,
|
||||||
|
errors: str | None = ...,
|
||||||
|
): ...
|
||||||
|
@overload
|
||||||
|
def __init__(
|
||||||
|
self: TemporaryFile[str],
|
||||||
|
mode: OpenTextMode,
|
||||||
|
buffering: int = ...,
|
||||||
|
encoding: str | None = ...,
|
||||||
|
newline: str | None = ...,
|
||||||
|
suffix: str | None = ...,
|
||||||
|
prefix: str | None = ...,
|
||||||
|
dir: str | None = ...,
|
||||||
|
*,
|
||||||
|
errors: str | None = ...,
|
||||||
|
): ...
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
mode: OpenTextMode | OpenBinaryMode = "w+b",
|
||||||
|
buffering: int = -1,
|
||||||
|
encoding: str | None = None,
|
||||||
|
newline: str | None = None,
|
||||||
|
suffix: str | None = None,
|
||||||
|
prefix: str | None = None,
|
||||||
|
dir: str | None = None,
|
||||||
|
*,
|
||||||
|
errors: str | None = None,
|
||||||
|
) -> None:
|
||||||
|
self.mode = mode
|
||||||
|
self.buffering = buffering
|
||||||
|
self.encoding = encoding
|
||||||
|
self.newline = newline
|
||||||
|
self.suffix: str | None = suffix
|
||||||
|
self.prefix: str | None = prefix
|
||||||
|
self.dir: str | None = dir
|
||||||
|
self.errors = errors
|
||||||
|
|
||||||
|
async def __aenter__(self) -> AsyncFile[AnyStr]:
|
||||||
|
fp = await to_thread.run_sync(
|
||||||
|
lambda: tempfile.TemporaryFile(
|
||||||
|
self.mode,
|
||||||
|
self.buffering,
|
||||||
|
self.encoding,
|
||||||
|
self.newline,
|
||||||
|
self.suffix,
|
||||||
|
self.prefix,
|
||||||
|
self.dir,
|
||||||
|
errors=self.errors,
|
||||||
|
)
|
||||||
|
)
|
||||||
|
self._async_file = AsyncFile(fp)
|
||||||
|
return self._async_file
|
||||||
|
|
||||||
|
async def __aexit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_value: BaseException | None,
|
||||||
|
traceback: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
await self._async_file.aclose()
|
||||||
|
|
||||||
|
|
||||||
|
class NamedTemporaryFile(Generic[AnyStr]):
|
||||||
|
"""
|
||||||
|
An asynchronous named temporary file that is automatically created and cleaned up.
|
||||||
|
|
||||||
|
This class provides an asynchronous context manager for a temporary file with a
|
||||||
|
visible name in the file system. It uses Python's standard
|
||||||
|
:func:`~tempfile.NamedTemporaryFile` function and wraps the file object with
|
||||||
|
:class:`AsyncFile` for asynchronous operations.
|
||||||
|
|
||||||
|
:param mode: The mode in which the file is opened. Defaults to "w+b".
|
||||||
|
:param buffering: The buffering policy (-1 means the default buffering).
|
||||||
|
:param encoding: The encoding used to decode or encode the file. Only applicable in
|
||||||
|
text mode.
|
||||||
|
:param newline: Controls how universal newlines mode works (only applicable in text
|
||||||
|
mode).
|
||||||
|
:param suffix: The suffix for the temporary file name.
|
||||||
|
:param prefix: The prefix for the temporary file name.
|
||||||
|
:param dir: The directory in which the temporary file is created.
|
||||||
|
:param delete: Whether to delete the file when it is closed.
|
||||||
|
:param errors: The error handling scheme used for encoding/decoding errors.
|
||||||
|
:param delete_on_close: (Python 3.12+) Whether to delete the file on close.
|
||||||
|
"""
|
||||||
|
|
||||||
|
_async_file: AsyncFile[AnyStr]
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def __init__(
|
||||||
|
self: NamedTemporaryFile[bytes],
|
||||||
|
mode: OpenBinaryMode = ...,
|
||||||
|
buffering: int = ...,
|
||||||
|
encoding: str | None = ...,
|
||||||
|
newline: str | None = ...,
|
||||||
|
suffix: str | None = ...,
|
||||||
|
prefix: str | None = ...,
|
||||||
|
dir: str | None = ...,
|
||||||
|
delete: bool = ...,
|
||||||
|
*,
|
||||||
|
errors: str | None = ...,
|
||||||
|
delete_on_close: bool = ...,
|
||||||
|
): ...
|
||||||
|
@overload
|
||||||
|
def __init__(
|
||||||
|
self: NamedTemporaryFile[str],
|
||||||
|
mode: OpenTextMode,
|
||||||
|
buffering: int = ...,
|
||||||
|
encoding: str | None = ...,
|
||||||
|
newline: str | None = ...,
|
||||||
|
suffix: str | None = ...,
|
||||||
|
prefix: str | None = ...,
|
||||||
|
dir: str | None = ...,
|
||||||
|
delete: bool = ...,
|
||||||
|
*,
|
||||||
|
errors: str | None = ...,
|
||||||
|
delete_on_close: bool = ...,
|
||||||
|
): ...
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
mode: OpenBinaryMode | OpenTextMode = "w+b",
|
||||||
|
buffering: int = -1,
|
||||||
|
encoding: str | None = None,
|
||||||
|
newline: str | None = None,
|
||||||
|
suffix: str | None = None,
|
||||||
|
prefix: str | None = None,
|
||||||
|
dir: str | None = None,
|
||||||
|
delete: bool = True,
|
||||||
|
*,
|
||||||
|
errors: str | None = None,
|
||||||
|
delete_on_close: bool = True,
|
||||||
|
) -> None:
|
||||||
|
self._params: dict[str, Any] = {
|
||||||
|
"mode": mode,
|
||||||
|
"buffering": buffering,
|
||||||
|
"encoding": encoding,
|
||||||
|
"newline": newline,
|
||||||
|
"suffix": suffix,
|
||||||
|
"prefix": prefix,
|
||||||
|
"dir": dir,
|
||||||
|
"delete": delete,
|
||||||
|
"errors": errors,
|
||||||
|
}
|
||||||
|
if sys.version_info >= (3, 12):
|
||||||
|
self._params["delete_on_close"] = delete_on_close
|
||||||
|
|
||||||
|
async def __aenter__(self) -> AsyncFile[AnyStr]:
|
||||||
|
fp = await to_thread.run_sync(
|
||||||
|
lambda: tempfile.NamedTemporaryFile(**self._params)
|
||||||
|
)
|
||||||
|
self._async_file = AsyncFile(fp)
|
||||||
|
return self._async_file
|
||||||
|
|
||||||
|
async def __aexit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_value: BaseException | None,
|
||||||
|
traceback: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
await self._async_file.aclose()
|
||||||
|
|
||||||
|
|
||||||
|
class SpooledTemporaryFile(AsyncFile[AnyStr]):
|
||||||
|
"""
|
||||||
|
An asynchronous spooled temporary file that starts in memory and is spooled to disk.
|
||||||
|
|
||||||
|
This class provides an asynchronous interface to a spooled temporary file, much like
|
||||||
|
Python's standard :class:`~tempfile.SpooledTemporaryFile`. It supports asynchronous
|
||||||
|
write operations and provides a method to force a rollover to disk.
|
||||||
|
|
||||||
|
:param max_size: Maximum size in bytes before the file is rolled over to disk.
|
||||||
|
:param mode: The mode in which the file is opened. Defaults to "w+b".
|
||||||
|
:param buffering: The buffering policy (-1 means the default buffering).
|
||||||
|
:param encoding: The encoding used to decode or encode the file (text mode only).
|
||||||
|
:param newline: Controls how universal newlines mode works (text mode only).
|
||||||
|
:param suffix: The suffix for the temporary file name.
|
||||||
|
:param prefix: The prefix for the temporary file name.
|
||||||
|
:param dir: The directory in which the temporary file is created.
|
||||||
|
:param errors: The error handling scheme used for encoding/decoding errors.
|
||||||
|
"""
|
||||||
|
|
||||||
|
_rolled: bool = False
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def __init__(
|
||||||
|
self: SpooledTemporaryFile[bytes],
|
||||||
|
max_size: int = ...,
|
||||||
|
mode: OpenBinaryMode = ...,
|
||||||
|
buffering: int = ...,
|
||||||
|
encoding: str | None = ...,
|
||||||
|
newline: str | None = ...,
|
||||||
|
suffix: str | None = ...,
|
||||||
|
prefix: str | None = ...,
|
||||||
|
dir: str | None = ...,
|
||||||
|
*,
|
||||||
|
errors: str | None = ...,
|
||||||
|
): ...
|
||||||
|
@overload
|
||||||
|
def __init__(
|
||||||
|
self: SpooledTemporaryFile[str],
|
||||||
|
max_size: int = ...,
|
||||||
|
mode: OpenTextMode = ...,
|
||||||
|
buffering: int = ...,
|
||||||
|
encoding: str | None = ...,
|
||||||
|
newline: str | None = ...,
|
||||||
|
suffix: str | None = ...,
|
||||||
|
prefix: str | None = ...,
|
||||||
|
dir: str | None = ...,
|
||||||
|
*,
|
||||||
|
errors: str | None = ...,
|
||||||
|
): ...
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
max_size: int = 0,
|
||||||
|
mode: OpenBinaryMode | OpenTextMode = "w+b",
|
||||||
|
buffering: int = -1,
|
||||||
|
encoding: str | None = None,
|
||||||
|
newline: str | None = None,
|
||||||
|
suffix: str | None = None,
|
||||||
|
prefix: str | None = None,
|
||||||
|
dir: str | None = None,
|
||||||
|
*,
|
||||||
|
errors: str | None = None,
|
||||||
|
) -> None:
|
||||||
|
self._tempfile_params: dict[str, Any] = {
|
||||||
|
"mode": mode,
|
||||||
|
"buffering": buffering,
|
||||||
|
"encoding": encoding,
|
||||||
|
"newline": newline,
|
||||||
|
"suffix": suffix,
|
||||||
|
"prefix": prefix,
|
||||||
|
"dir": dir,
|
||||||
|
"errors": errors,
|
||||||
|
}
|
||||||
|
self._max_size = max_size
|
||||||
|
if "b" in mode:
|
||||||
|
super().__init__(BytesIO()) # type: ignore[arg-type]
|
||||||
|
else:
|
||||||
|
super().__init__(
|
||||||
|
TextIOWrapper( # type: ignore[arg-type]
|
||||||
|
BytesIO(),
|
||||||
|
encoding=encoding,
|
||||||
|
errors=errors,
|
||||||
|
newline=newline,
|
||||||
|
write_through=True,
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
if not self._rolled:
|
||||||
|
self._fp.close()
|
||||||
|
return
|
||||||
|
|
||||||
|
await super().aclose()
|
||||||
|
|
||||||
|
async def _check(self) -> None:
|
||||||
|
if self._rolled or self._fp.tell() <= self._max_size:
|
||||||
|
return
|
||||||
|
|
||||||
|
await self.rollover()
|
||||||
|
|
||||||
|
async def rollover(self) -> None:
|
||||||
|
if self._rolled:
|
||||||
|
return
|
||||||
|
|
||||||
|
self._rolled = True
|
||||||
|
buffer = self._fp
|
||||||
|
buffer.seek(0)
|
||||||
|
self._fp = await to_thread.run_sync(
|
||||||
|
lambda: tempfile.TemporaryFile(**self._tempfile_params)
|
||||||
|
)
|
||||||
|
await self.write(buffer.read())
|
||||||
|
buffer.close()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def closed(self) -> bool:
|
||||||
|
return self._fp.closed
|
||||||
|
|
||||||
|
async def read(self, size: int = -1) -> AnyStr:
|
||||||
|
if not self._rolled:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
return self._fp.read(size)
|
||||||
|
|
||||||
|
return await super().read(size) # type: ignore[return-value]
|
||||||
|
|
||||||
|
async def read1(self: SpooledTemporaryFile[bytes], size: int = -1) -> bytes:
|
||||||
|
if not self._rolled:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
return self._fp.read1(size)
|
||||||
|
|
||||||
|
return await super().read1(size)
|
||||||
|
|
||||||
|
async def readline(self) -> AnyStr:
|
||||||
|
if not self._rolled:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
return self._fp.readline()
|
||||||
|
|
||||||
|
return await super().readline() # type: ignore[return-value]
|
||||||
|
|
||||||
|
async def readlines(self) -> list[AnyStr]:
|
||||||
|
if not self._rolled:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
return self._fp.readlines()
|
||||||
|
|
||||||
|
return await super().readlines() # type: ignore[return-value]
|
||||||
|
|
||||||
|
async def readinto(self: SpooledTemporaryFile[bytes], b: WriteableBuffer) -> int:
|
||||||
|
if not self._rolled:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
return self._fp.readinto(b)
|
||||||
|
|
||||||
|
return await super().readinto(b)
|
||||||
|
|
||||||
|
async def readinto1(self: SpooledTemporaryFile[bytes], b: WriteableBuffer) -> int:
|
||||||
|
if not self._rolled:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
return self._fp.readinto1(b)
|
||||||
|
|
||||||
|
return await super().readinto1(b)
|
||||||
|
|
||||||
|
async def seek(self, offset: int, whence: int | None = os.SEEK_SET) -> int:
|
||||||
|
if not self._rolled:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
return self._fp.seek(offset, whence)
|
||||||
|
|
||||||
|
return await super().seek(offset, whence)
|
||||||
|
|
||||||
|
async def tell(self) -> int:
|
||||||
|
if not self._rolled:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
return self._fp.tell()
|
||||||
|
|
||||||
|
return await super().tell()
|
||||||
|
|
||||||
|
async def truncate(self, size: int | None = None) -> int:
|
||||||
|
if not self._rolled:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
return self._fp.truncate(size)
|
||||||
|
|
||||||
|
return await super().truncate(size)
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def write(self: SpooledTemporaryFile[bytes], b: ReadableBuffer) -> int: ...
|
||||||
|
@overload
|
||||||
|
async def write(self: SpooledTemporaryFile[str], b: str) -> int: ...
|
||||||
|
|
||||||
|
async def write(self, b: ReadableBuffer | str) -> int:
|
||||||
|
"""
|
||||||
|
Asynchronously write data to the spooled temporary file.
|
||||||
|
|
||||||
|
If the file has not yet been rolled over, the data is written synchronously,
|
||||||
|
and a rollover is triggered if the size exceeds the maximum size.
|
||||||
|
|
||||||
|
:param s: The data to write.
|
||||||
|
:return: The number of bytes written.
|
||||||
|
:raises RuntimeError: If the underlying file is not initialized.
|
||||||
|
|
||||||
|
"""
|
||||||
|
if not self._rolled:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
result = self._fp.write(b)
|
||||||
|
await self._check()
|
||||||
|
return result
|
||||||
|
|
||||||
|
return await super().write(b) # type: ignore[misc]
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def writelines(
|
||||||
|
self: SpooledTemporaryFile[bytes], lines: Iterable[ReadableBuffer]
|
||||||
|
) -> None: ...
|
||||||
|
@overload
|
||||||
|
async def writelines(
|
||||||
|
self: SpooledTemporaryFile[str], lines: Iterable[str]
|
||||||
|
) -> None: ...
|
||||||
|
|
||||||
|
async def writelines(self, lines: Iterable[str] | Iterable[ReadableBuffer]) -> None:
|
||||||
|
"""
|
||||||
|
Asynchronously write a list of lines to the spooled temporary file.
|
||||||
|
|
||||||
|
If the file has not yet been rolled over, the lines are written synchronously,
|
||||||
|
and a rollover is triggered if the size exceeds the maximum size.
|
||||||
|
|
||||||
|
:param lines: An iterable of lines to write.
|
||||||
|
:raises RuntimeError: If the underlying file is not initialized.
|
||||||
|
|
||||||
|
"""
|
||||||
|
if not self._rolled:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
result = self._fp.writelines(lines)
|
||||||
|
await self._check()
|
||||||
|
return result
|
||||||
|
|
||||||
|
return await super().writelines(lines) # type: ignore[misc]
|
||||||
|
|
||||||
|
|
||||||
|
class TemporaryDirectory(Generic[AnyStr]):
|
||||||
|
"""
|
||||||
|
An asynchronous temporary directory that is created and cleaned up automatically.
|
||||||
|
|
||||||
|
This class provides an asynchronous context manager for creating a temporary
|
||||||
|
directory. It wraps Python's standard :class:`~tempfile.TemporaryDirectory` to
|
||||||
|
perform directory creation and cleanup operations in a background thread.
|
||||||
|
|
||||||
|
:param suffix: Suffix to be added to the temporary directory name.
|
||||||
|
:param prefix: Prefix to be added to the temporary directory name.
|
||||||
|
:param dir: The parent directory where the temporary directory is created.
|
||||||
|
:param ignore_cleanup_errors: Whether to ignore errors during cleanup
|
||||||
|
:param delete: Whether to delete the directory upon closing (Python 3.12+).
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
suffix: AnyStr | None = None,
|
||||||
|
prefix: AnyStr | None = None,
|
||||||
|
dir: AnyStr | None = None,
|
||||||
|
*,
|
||||||
|
ignore_cleanup_errors: bool = False,
|
||||||
|
delete: bool = True,
|
||||||
|
) -> None:
|
||||||
|
self.suffix: AnyStr | None = suffix
|
||||||
|
self.prefix: AnyStr | None = prefix
|
||||||
|
self.dir: AnyStr | None = dir
|
||||||
|
self.ignore_cleanup_errors = ignore_cleanup_errors
|
||||||
|
self.delete = delete
|
||||||
|
|
||||||
|
self._tempdir: tempfile.TemporaryDirectory | None = None
|
||||||
|
|
||||||
|
async def __aenter__(self) -> str:
|
||||||
|
params: dict[str, Any] = {
|
||||||
|
"suffix": self.suffix,
|
||||||
|
"prefix": self.prefix,
|
||||||
|
"dir": self.dir,
|
||||||
|
"ignore_cleanup_errors": self.ignore_cleanup_errors,
|
||||||
|
}
|
||||||
|
if sys.version_info >= (3, 12):
|
||||||
|
params["delete"] = self.delete
|
||||||
|
|
||||||
|
self._tempdir = await to_thread.run_sync(
|
||||||
|
lambda: tempfile.TemporaryDirectory(**params)
|
||||||
|
)
|
||||||
|
return await to_thread.run_sync(self._tempdir.__enter__)
|
||||||
|
|
||||||
|
async def __aexit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_value: BaseException | None,
|
||||||
|
traceback: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
if self._tempdir is not None:
|
||||||
|
with CancelScope(shield=True):
|
||||||
|
await to_thread.run_sync(
|
||||||
|
self._tempdir.__exit__, exc_type, exc_value, traceback
|
||||||
|
)
|
||||||
|
|
||||||
|
async def cleanup(self) -> None:
|
||||||
|
if self._tempdir is not None:
|
||||||
|
await to_thread.run_sync(self._tempdir.cleanup)
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def mkstemp(
|
||||||
|
suffix: str | None = None,
|
||||||
|
prefix: str | None = None,
|
||||||
|
dir: str | None = None,
|
||||||
|
text: bool = False,
|
||||||
|
) -> tuple[int, str]: ...
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def mkstemp(
|
||||||
|
suffix: bytes | None = None,
|
||||||
|
prefix: bytes | None = None,
|
||||||
|
dir: bytes | None = None,
|
||||||
|
text: bool = False,
|
||||||
|
) -> tuple[int, bytes]: ...
|
||||||
|
|
||||||
|
|
||||||
|
async def mkstemp(
|
||||||
|
suffix: AnyStr | None = None,
|
||||||
|
prefix: AnyStr | None = None,
|
||||||
|
dir: AnyStr | None = None,
|
||||||
|
text: bool = False,
|
||||||
|
) -> tuple[int, str | bytes]:
|
||||||
|
"""
|
||||||
|
Asynchronously create a temporary file and return an OS-level handle and the file
|
||||||
|
name.
|
||||||
|
|
||||||
|
This function wraps `tempfile.mkstemp` and executes it in a background thread.
|
||||||
|
|
||||||
|
:param suffix: Suffix to be added to the file name.
|
||||||
|
:param prefix: Prefix to be added to the file name.
|
||||||
|
:param dir: Directory in which the temporary file is created.
|
||||||
|
:param text: Whether the file is opened in text mode.
|
||||||
|
:return: A tuple containing the file descriptor and the file name.
|
||||||
|
|
||||||
|
"""
|
||||||
|
return await to_thread.run_sync(tempfile.mkstemp, suffix, prefix, dir, text)
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def mkdtemp(
|
||||||
|
suffix: str | None = None,
|
||||||
|
prefix: str | None = None,
|
||||||
|
dir: str | None = None,
|
||||||
|
) -> str: ...
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def mkdtemp(
|
||||||
|
suffix: bytes | None = None,
|
||||||
|
prefix: bytes | None = None,
|
||||||
|
dir: bytes | None = None,
|
||||||
|
) -> bytes: ...
|
||||||
|
|
||||||
|
|
||||||
|
async def mkdtemp(
|
||||||
|
suffix: AnyStr | None = None,
|
||||||
|
prefix: AnyStr | None = None,
|
||||||
|
dir: AnyStr | None = None,
|
||||||
|
) -> str | bytes:
|
||||||
|
"""
|
||||||
|
Asynchronously create a temporary directory and return its path.
|
||||||
|
|
||||||
|
This function wraps `tempfile.mkdtemp` and executes it in a background thread.
|
||||||
|
|
||||||
|
:param suffix: Suffix to be added to the directory name.
|
||||||
|
:param prefix: Prefix to be added to the directory name.
|
||||||
|
:param dir: Parent directory where the temporary directory is created.
|
||||||
|
:return: The path of the created temporary directory.
|
||||||
|
|
||||||
|
"""
|
||||||
|
return await to_thread.run_sync(tempfile.mkdtemp, suffix, prefix, dir)
|
||||||
|
|
||||||
|
|
||||||
|
async def gettempdir() -> str:
|
||||||
|
"""
|
||||||
|
Asynchronously return the name of the directory used for temporary files.
|
||||||
|
|
||||||
|
This function wraps `tempfile.gettempdir` and executes it in a background thread.
|
||||||
|
|
||||||
|
:return: The path of the temporary directory as a string.
|
||||||
|
|
||||||
|
"""
|
||||||
|
return await to_thread.run_sync(tempfile.gettempdir)
|
||||||
|
|
||||||
|
|
||||||
|
async def gettempdirb() -> bytes:
|
||||||
|
"""
|
||||||
|
Asynchronously return the name of the directory used for temporary files in bytes.
|
||||||
|
|
||||||
|
This function wraps `tempfile.gettempdirb` and executes it in a background thread.
|
||||||
|
|
||||||
|
:return: The path of the temporary directory as bytes.
|
||||||
|
|
||||||
|
"""
|
||||||
|
return await to_thread.run_sync(tempfile.gettempdirb)
|
||||||
@@ -0,0 +1,82 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from collections.abc import Awaitable, Generator
|
||||||
|
from typing import Any, cast
|
||||||
|
|
||||||
|
from ._eventloop import get_async_backend
|
||||||
|
|
||||||
|
|
||||||
|
class TaskInfo:
|
||||||
|
"""
|
||||||
|
Represents an asynchronous task.
|
||||||
|
|
||||||
|
:ivar int id: the unique identifier of the task
|
||||||
|
:ivar parent_id: the identifier of the parent task, if any
|
||||||
|
:vartype parent_id: Optional[int]
|
||||||
|
:ivar str name: the description of the task (if any)
|
||||||
|
:ivar ~collections.abc.Coroutine coro: the coroutine object of the task
|
||||||
|
"""
|
||||||
|
|
||||||
|
__slots__ = "_name", "coro", "id", "name", "parent_id"
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
id: int,
|
||||||
|
parent_id: int | None,
|
||||||
|
name: str | None,
|
||||||
|
coro: Generator[Any, Any, Any] | Awaitable[Any],
|
||||||
|
):
|
||||||
|
func = get_current_task
|
||||||
|
self._name = f"{func.__module__}.{func.__qualname__}"
|
||||||
|
self.id: int = id
|
||||||
|
self.parent_id: int | None = parent_id
|
||||||
|
self.name: str | None = name
|
||||||
|
self.coro: Generator[Any, Any, Any] | Awaitable[Any] = coro
|
||||||
|
|
||||||
|
def __eq__(self, other: object) -> bool:
|
||||||
|
if isinstance(other, TaskInfo):
|
||||||
|
return self.id == other.id
|
||||||
|
|
||||||
|
return NotImplemented
|
||||||
|
|
||||||
|
def __hash__(self) -> int:
|
||||||
|
return hash(self.id)
|
||||||
|
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
return f"{self.__class__.__name__}(id={self.id!r}, name={self.name!r})"
|
||||||
|
|
||||||
|
def has_pending_cancellation(self) -> bool:
|
||||||
|
"""
|
||||||
|
Return ``True`` if the task has a cancellation pending, ``False`` otherwise.
|
||||||
|
|
||||||
|
"""
|
||||||
|
return False
|
||||||
|
|
||||||
|
|
||||||
|
def get_current_task() -> TaskInfo:
|
||||||
|
"""
|
||||||
|
Return the current task.
|
||||||
|
|
||||||
|
:return: a representation of the current task
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
"""
|
||||||
|
return get_async_backend().get_current_task()
|
||||||
|
|
||||||
|
|
||||||
|
def get_running_tasks() -> list[TaskInfo]:
|
||||||
|
"""
|
||||||
|
Return a list of running tasks in the current event loop.
|
||||||
|
|
||||||
|
:return: a list of task info objects
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
"""
|
||||||
|
return cast("list[TaskInfo]", get_async_backend().get_running_tasks())
|
||||||
|
|
||||||
|
|
||||||
|
async def wait_all_tasks_blocked() -> None:
|
||||||
|
"""Wait until all other tasks are waiting for something."""
|
||||||
|
await get_async_backend().wait_all_tasks_blocked()
|
||||||
@@ -0,0 +1,85 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import sys
|
||||||
|
from collections.abc import Callable, Mapping
|
||||||
|
from typing import Any, TypeVar, final, overload
|
||||||
|
|
||||||
|
from ._exceptions import TypedAttributeLookupError
|
||||||
|
|
||||||
|
if sys.version_info < (3, 15):
|
||||||
|
from typing_extensions import sentinel
|
||||||
|
|
||||||
|
T_Attr = TypeVar("T_Attr")
|
||||||
|
T_Default = TypeVar("T_Default")
|
||||||
|
undefined = sentinel("undefined")
|
||||||
|
|
||||||
|
|
||||||
|
def typed_attribute() -> Any:
|
||||||
|
"""Return a unique object, used to mark typed attributes."""
|
||||||
|
return object()
|
||||||
|
|
||||||
|
|
||||||
|
class TypedAttributeSet:
|
||||||
|
"""
|
||||||
|
Superclass for typed attribute collections.
|
||||||
|
|
||||||
|
Checks that every public attribute of every subclass has a type annotation.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init_subclass__(cls) -> None:
|
||||||
|
annotations: dict[str, Any] = getattr(cls, "__annotations__", {})
|
||||||
|
for attrname in dir(cls):
|
||||||
|
if not attrname.startswith("_") and attrname not in annotations:
|
||||||
|
raise TypeError(
|
||||||
|
f"Attribute {attrname!r} is missing its type annotation"
|
||||||
|
)
|
||||||
|
|
||||||
|
super().__init_subclass__()
|
||||||
|
|
||||||
|
|
||||||
|
class TypedAttributeProvider:
|
||||||
|
"""Base class for classes that wish to provide typed extra attributes."""
|
||||||
|
|
||||||
|
@property
|
||||||
|
def extra_attributes(self) -> Mapping[T_Attr, Callable[[], T_Attr]]:
|
||||||
|
"""
|
||||||
|
A mapping of the extra attributes to callables that return the corresponding
|
||||||
|
values.
|
||||||
|
|
||||||
|
If the provider wraps another provider, the attributes from that wrapper should
|
||||||
|
also be included in the returned mapping (but the wrapper may override the
|
||||||
|
callables from the wrapped instance).
|
||||||
|
|
||||||
|
"""
|
||||||
|
return {}
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def extra(self, attribute: T_Attr) -> T_Attr: ...
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def extra(self, attribute: T_Attr, default: T_Default) -> T_Attr | T_Default: ...
|
||||||
|
|
||||||
|
@final
|
||||||
|
def extra(self, attribute: Any, default: object = undefined) -> object:
|
||||||
|
"""
|
||||||
|
extra(attribute, default=undefined)
|
||||||
|
|
||||||
|
Return the value of the given typed extra attribute.
|
||||||
|
|
||||||
|
:param attribute: the attribute (member of a :class:`~TypedAttributeSet`) to
|
||||||
|
look for
|
||||||
|
:param default: the value that should be returned if no value is found for the
|
||||||
|
attribute
|
||||||
|
:raises ~anyio.TypedAttributeLookupError: if the search failed and no default
|
||||||
|
value was given
|
||||||
|
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
getter = self.extra_attributes[attribute]
|
||||||
|
except KeyError:
|
||||||
|
if default is undefined:
|
||||||
|
raise TypedAttributeLookupError("Attribute not found") from None
|
||||||
|
else:
|
||||||
|
return default
|
||||||
|
|
||||||
|
return getter()
|
||||||
@@ -0,0 +1,176 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"fix_package_names",
|
||||||
|
"install_lazy_importer",
|
||||||
|
"set_deprecated_aliases",
|
||||||
|
)
|
||||||
|
|
||||||
|
import ast
|
||||||
|
import inspect
|
||||||
|
import sys
|
||||||
|
import warnings
|
||||||
|
from importlib import import_module
|
||||||
|
from types import ModuleType
|
||||||
|
from typing import Any
|
||||||
|
|
||||||
|
|
||||||
|
def install_lazy_importer() -> bool:
|
||||||
|
module_globals = sys._getframe(1).f_globals
|
||||||
|
module_name = module_globals["__name__"]
|
||||||
|
module_prefix = module_name + "."
|
||||||
|
module = sys.modules[module_name]
|
||||||
|
lazy_map, deprecated_aliases, submodule_names = _build_lazy_map(module)
|
||||||
|
names = sorted(lazy_map)
|
||||||
|
|
||||||
|
# Delete symbols that are not part of the API
|
||||||
|
del module_globals["TYPE_CHECKING"]
|
||||||
|
del module_globals["install_lazy_importer"]
|
||||||
|
|
||||||
|
if not lazy_map and not deprecated_aliases:
|
||||||
|
return False
|
||||||
|
|
||||||
|
def __getattr__(name: str) -> Any:
|
||||||
|
if new_name := deprecated_aliases.get(name):
|
||||||
|
emit_deprecation_warning(module_name, name, new_name)
|
||||||
|
target_mod, target_attr = new_name.rsplit(".", 1)
|
||||||
|
elif name in submodule_names:
|
||||||
|
target_mod, target_attr = "." + name, ""
|
||||||
|
else:
|
||||||
|
try:
|
||||||
|
target_mod, target_attr = lazy_map[name]
|
||||||
|
except KeyError:
|
||||||
|
raise AttributeError(
|
||||||
|
f"module {module_name!r} has no attribute {name!r}"
|
||||||
|
) from None
|
||||||
|
|
||||||
|
imported = import_module(target_mod, module_name)
|
||||||
|
value = getattr(imported, target_attr) if target_attr else imported
|
||||||
|
|
||||||
|
# patch the module name to match
|
||||||
|
if (
|
||||||
|
getattr(value, "__module__", "").startswith(module_prefix)
|
||||||
|
and name not in deprecated_aliases
|
||||||
|
):
|
||||||
|
value.__module__ = module_name
|
||||||
|
|
||||||
|
module_globals[name] = value
|
||||||
|
return value
|
||||||
|
|
||||||
|
def __dir__() -> list[str]:
|
||||||
|
return names
|
||||||
|
|
||||||
|
module_globals["__dir__"] = __dir__
|
||||||
|
module_globals["__getattr__"] = __getattr__
|
||||||
|
module_globals.pop("fix_package_names", None)
|
||||||
|
module_globals.pop("set_deprecated_aliases", None)
|
||||||
|
return True
|
||||||
|
|
||||||
|
|
||||||
|
def fix_package_names() -> None:
|
||||||
|
module_globals = sys._getframe(1).f_globals
|
||||||
|
module_prefix = module_globals["__name__"] + "."
|
||||||
|
del module_globals[fix_package_names.__name__]
|
||||||
|
for value in module_globals.values():
|
||||||
|
if modname := getattr(value, "__module__", ""):
|
||||||
|
if modname.startswith(module_prefix):
|
||||||
|
parts = modname.split(".")
|
||||||
|
value.__module__ = ".".join(
|
||||||
|
part for part in parts if not part.startswith("_")
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def emit_deprecation_warning(module_name: str, name: str, target: str) -> None:
|
||||||
|
warnings.warn(
|
||||||
|
f"The {module_name}.{name} alias is deprecated, use {target} instead.",
|
||||||
|
DeprecationWarning,
|
||||||
|
stacklevel=3,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def set_deprecated_aliases(aliases: dict[str, str]) -> None:
|
||||||
|
module_globals = sys._getframe(1).f_globals
|
||||||
|
module_name = module_globals["__name__"]
|
||||||
|
del module_globals[set_deprecated_aliases.__name__]
|
||||||
|
|
||||||
|
def __getattr__(name: str) -> Any:
|
||||||
|
try:
|
||||||
|
target = aliases[name]
|
||||||
|
except KeyError:
|
||||||
|
raise AttributeError(
|
||||||
|
f"module {module_name!r} has no attribute {name!r}"
|
||||||
|
) from None
|
||||||
|
|
||||||
|
emit_deprecation_warning(module_name, name, target)
|
||||||
|
target_modname, attrname = target.rsplit(".", 1)
|
||||||
|
module = import_module(target_modname)
|
||||||
|
return getattr(module, attrname)
|
||||||
|
|
||||||
|
sys.modules[module_name].__dict__["__getattr__"] = __getattr__
|
||||||
|
|
||||||
|
|
||||||
|
def _build_lazy_map(
|
||||||
|
module: ModuleType,
|
||||||
|
) -> tuple[dict[str, tuple[str, str]], dict[str, str], list[str]]:
|
||||||
|
try:
|
||||||
|
source = inspect.getsource(module)
|
||||||
|
except OSError:
|
||||||
|
return {}, {}, []
|
||||||
|
|
||||||
|
tree = compile(source, module.__file__ or "", "exec", ast.PyCF_ONLY_AST)
|
||||||
|
assert isinstance(tree, ast.Module)
|
||||||
|
out: dict[str, tuple[str, str]] = {}
|
||||||
|
deprecated_aliases: dict[str, str] = {}
|
||||||
|
submodule_names: list[str] = []
|
||||||
|
|
||||||
|
for node in tree.body:
|
||||||
|
if not isinstance(node, ast.If) or not _is_type_checking_block(node.test):
|
||||||
|
continue
|
||||||
|
|
||||||
|
for stmt in node.body:
|
||||||
|
match stmt:
|
||||||
|
case ast.ImportFrom():
|
||||||
|
if stmt.module is None:
|
||||||
|
submodule_names.extend(alias.name for alias in stmt.names)
|
||||||
|
else:
|
||||||
|
base = "." * stmt.level + (stmt.module or "")
|
||||||
|
for alias in stmt.names:
|
||||||
|
if alias.name == "*":
|
||||||
|
raise RuntimeError("star imports not supported")
|
||||||
|
|
||||||
|
exported = alias.asname or alias.name
|
||||||
|
out[exported] = (base, alias.name)
|
||||||
|
case ast.Expr() if isinstance(stmt.value, ast.Call):
|
||||||
|
call = stmt.value
|
||||||
|
if (
|
||||||
|
isinstance(call.func, ast.Name)
|
||||||
|
and call.func.id == "set_deprecated_aliases"
|
||||||
|
):
|
||||||
|
arg0 = call.args[0]
|
||||||
|
assert isinstance(arg0, ast.Dict)
|
||||||
|
for key, value in zip(arg0.keys, arg0.values, strict=True):
|
||||||
|
assert isinstance(key, ast.Constant)
|
||||||
|
assert isinstance(key.value, str)
|
||||||
|
assert isinstance(value, ast.Constant)
|
||||||
|
assert isinstance(value.value, str)
|
||||||
|
deprecated_aliases[key.value] = value.value
|
||||||
|
|
||||||
|
return out, deprecated_aliases, submodule_names
|
||||||
|
|
||||||
|
|
||||||
|
def _is_type_checking_block(test: ast.AST) -> bool:
|
||||||
|
if not isinstance(test, ast.BoolOp):
|
||||||
|
return False
|
||||||
|
|
||||||
|
subtest = test.values[0]
|
||||||
|
match subtest:
|
||||||
|
case ast.Name():
|
||||||
|
return subtest.id == "TYPE_CHECKING"
|
||||||
|
case ast.Attribute():
|
||||||
|
return (
|
||||||
|
isinstance(subtest.value, ast.Name)
|
||||||
|
and subtest.value.id == "typing"
|
||||||
|
and subtest.attr == "TYPE_CHECKING"
|
||||||
|
)
|
||||||
|
case _:
|
||||||
|
return False
|
||||||
@@ -0,0 +1,63 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from typing import TYPE_CHECKING
|
||||||
|
|
||||||
|
from .._lazyimport import (
|
||||||
|
fix_package_names,
|
||||||
|
install_lazy_importer,
|
||||||
|
set_deprecated_aliases,
|
||||||
|
)
|
||||||
|
|
||||||
|
if TYPE_CHECKING or not install_lazy_importer():
|
||||||
|
from ._eventloop import AsyncBackend as AsyncBackend
|
||||||
|
from ._resources import AsyncResource as AsyncResource
|
||||||
|
from ._sockets import ConnectedUDPSocket as ConnectedUDPSocket
|
||||||
|
from ._sockets import ConnectedUNIXDatagramSocket as ConnectedUNIXDatagramSocket
|
||||||
|
from ._sockets import IPAddressType as IPAddressType
|
||||||
|
from ._sockets import IPSockAddrType as IPSockAddrType
|
||||||
|
from ._sockets import SocketAttribute as SocketAttribute
|
||||||
|
from ._sockets import SocketListener as SocketListener
|
||||||
|
from ._sockets import SocketStream as SocketStream
|
||||||
|
from ._sockets import UDPPacketType as UDPPacketType
|
||||||
|
from ._sockets import UDPSocket as UDPSocket
|
||||||
|
from ._sockets import UNIXDatagramPacketType as UNIXDatagramPacketType
|
||||||
|
from ._sockets import UNIXDatagramSocket as UNIXDatagramSocket
|
||||||
|
from ._sockets import UNIXSocketStream as UNIXSocketStream
|
||||||
|
from ._streams import AnyByteReceiveStream as AnyByteReceiveStream
|
||||||
|
from ._streams import AnyByteSendStream as AnyByteSendStream
|
||||||
|
from ._streams import AnyByteStream as AnyByteStream
|
||||||
|
from ._streams import AnyByteStreamConnectable as AnyByteStreamConnectable
|
||||||
|
from ._streams import (
|
||||||
|
AnyUnreliableByteReceiveStream as AnyUnreliableByteReceiveStream,
|
||||||
|
)
|
||||||
|
from ._streams import AnyUnreliableByteSendStream as AnyUnreliableByteSendStream
|
||||||
|
from ._streams import AnyUnreliableByteStream as AnyUnreliableByteStream
|
||||||
|
from ._streams import ByteReceiveStream as ByteReceiveStream
|
||||||
|
from ._streams import ByteSendStream as ByteSendStream
|
||||||
|
from ._streams import ByteStream as ByteStream
|
||||||
|
from ._streams import ByteStreamConnectable as ByteStreamConnectable
|
||||||
|
from ._streams import Listener as Listener
|
||||||
|
from ._streams import ObjectReceiveStream as ObjectReceiveStream
|
||||||
|
from ._streams import ObjectSendStream as ObjectSendStream
|
||||||
|
from ._streams import ObjectStream as ObjectStream
|
||||||
|
from ._streams import ObjectStreamConnectable as ObjectStreamConnectable
|
||||||
|
from ._streams import UnreliableObjectReceiveStream as UnreliableObjectReceiveStream
|
||||||
|
from ._streams import UnreliableObjectSendStream as UnreliableObjectSendStream
|
||||||
|
from ._streams import UnreliableObjectStream as UnreliableObjectStream
|
||||||
|
from ._subprocesses import Process as Process
|
||||||
|
from ._tasks import TaskGroup as TaskGroup
|
||||||
|
from ._tasks import TaskStatus as TaskStatus
|
||||||
|
from ._testing import TestRunner as TestRunner
|
||||||
|
|
||||||
|
fix_package_names()
|
||||||
|
set_deprecated_aliases(
|
||||||
|
{
|
||||||
|
"CapacityLimiter": "anyio.CapacityLimiter",
|
||||||
|
"Condition": "anyio.Condition",
|
||||||
|
"Event": "anyio.Event",
|
||||||
|
"Lock": "anyio.Lock",
|
||||||
|
"Semaphore": "anyio.Semaphore",
|
||||||
|
"CancelScope": "anyio.CancelScope",
|
||||||
|
"BlockingPortal": "anyio.from_thread.BlockingPortal",
|
||||||
|
}
|
||||||
|
)
|
||||||
@@ -0,0 +1,428 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import math
|
||||||
|
import sys
|
||||||
|
from abc import ABCMeta, abstractmethod
|
||||||
|
from collections.abc import (
|
||||||
|
AsyncIterator,
|
||||||
|
Awaitable,
|
||||||
|
Callable,
|
||||||
|
Coroutine,
|
||||||
|
Iterable,
|
||||||
|
Mapping,
|
||||||
|
Sequence,
|
||||||
|
)
|
||||||
|
from contextlib import AbstractContextManager
|
||||||
|
from os import PathLike
|
||||||
|
from signal import Signals
|
||||||
|
from socket import AddressFamily, SocketKind, socket
|
||||||
|
from typing import (
|
||||||
|
IO,
|
||||||
|
TYPE_CHECKING,
|
||||||
|
Any,
|
||||||
|
TypeAlias,
|
||||||
|
TypeVar,
|
||||||
|
overload,
|
||||||
|
)
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import TypeVarTuple, Unpack
|
||||||
|
else:
|
||||||
|
from typing_extensions import TypeVarTuple, Unpack
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
from _typeshed import FileDescriptorLike
|
||||||
|
|
||||||
|
from .._core._synchronization import CapacityLimiter, Event, Lock, Semaphore
|
||||||
|
from .._core._tasks import CancelScope
|
||||||
|
from .._core._testing import TaskInfo
|
||||||
|
from ._sockets import (
|
||||||
|
ConnectedUDPSocket,
|
||||||
|
ConnectedUNIXDatagramSocket,
|
||||||
|
IPSockAddrType,
|
||||||
|
SocketListener,
|
||||||
|
SocketStream,
|
||||||
|
UDPSocket,
|
||||||
|
UNIXDatagramSocket,
|
||||||
|
UNIXSocketStream,
|
||||||
|
)
|
||||||
|
from ._subprocesses import Process
|
||||||
|
from ._tasks import TaskGroup
|
||||||
|
from ._testing import TestRunner
|
||||||
|
|
||||||
|
T_Retval = TypeVar("T_Retval")
|
||||||
|
T_co = TypeVar("T_co", covariant=True)
|
||||||
|
PosArgsT = TypeVarTuple("PosArgsT")
|
||||||
|
StrOrBytesPath: TypeAlias = str | bytes | PathLike[str] | PathLike[bytes]
|
||||||
|
|
||||||
|
|
||||||
|
class AsyncBackend(metaclass=ABCMeta):
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def run(
|
||||||
|
cls,
|
||||||
|
func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval]],
|
||||||
|
args: tuple[Unpack[PosArgsT]],
|
||||||
|
kwargs: dict[str, Any],
|
||||||
|
options: dict[str, Any],
|
||||||
|
) -> T_Retval:
|
||||||
|
"""
|
||||||
|
Run the given coroutine function in an asynchronous event loop.
|
||||||
|
|
||||||
|
The current thread must not be already running an event loop.
|
||||||
|
|
||||||
|
:param func: a coroutine function
|
||||||
|
:param args: positional arguments to ``func``
|
||||||
|
:param kwargs: positional arguments to ``func``
|
||||||
|
:param options: keyword arguments to call the backend ``run()`` implementation
|
||||||
|
with
|
||||||
|
:return: the return value of the coroutine function
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def current_token(cls) -> object:
|
||||||
|
"""
|
||||||
|
Return an object that allows other threads to run code inside the event loop.
|
||||||
|
|
||||||
|
:return: a token object, specific to the event loop running in the current
|
||||||
|
thread
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def current_time(cls) -> float:
|
||||||
|
"""
|
||||||
|
Return the current value of the event loop's internal clock.
|
||||||
|
|
||||||
|
:return: the clock value (seconds)
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def cancelled_exception_class(cls) -> type[BaseException]:
|
||||||
|
"""Return the exception class that is raised in a task if it's cancelled."""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def checkpoint(cls) -> None:
|
||||||
|
"""
|
||||||
|
Check if the task has been cancelled, and allow rescheduling of other tasks.
|
||||||
|
|
||||||
|
This is effectively the same as running :meth:`checkpoint_if_cancelled` and then
|
||||||
|
:meth:`cancel_shielded_checkpoint`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
async def checkpoint_if_cancelled(cls) -> None:
|
||||||
|
"""
|
||||||
|
Check if the current task group has been cancelled.
|
||||||
|
|
||||||
|
This will check if the task has been cancelled, but will not allow other tasks
|
||||||
|
to be scheduled if not.
|
||||||
|
|
||||||
|
"""
|
||||||
|
if cls.current_effective_deadline() == -math.inf:
|
||||||
|
await cls.checkpoint()
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
async def cancel_shielded_checkpoint(cls) -> None:
|
||||||
|
"""
|
||||||
|
Allow the rescheduling of other tasks.
|
||||||
|
|
||||||
|
This will give other tasks the opportunity to run, but without checking if the
|
||||||
|
current task group has been cancelled, unlike with :meth:`checkpoint`.
|
||||||
|
|
||||||
|
"""
|
||||||
|
with cls.create_cancel_scope(shield=True):
|
||||||
|
await cls.sleep(0)
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def sleep(cls, delay: float) -> None:
|
||||||
|
"""
|
||||||
|
Pause the current task for the specified duration.
|
||||||
|
|
||||||
|
:param delay: the duration, in seconds
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def create_cancel_scope(
|
||||||
|
cls, *, deadline: float = math.inf, shield: bool = False
|
||||||
|
) -> CancelScope:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def current_effective_deadline(cls) -> float:
|
||||||
|
"""
|
||||||
|
Return the nearest deadline among all the cancel scopes effective for the
|
||||||
|
current task.
|
||||||
|
|
||||||
|
:return:
|
||||||
|
- a clock value from the event loop's internal clock
|
||||||
|
- ``inf`` if there is no deadline in effect
|
||||||
|
- ``-inf`` if the current scope has been cancelled
|
||||||
|
:rtype: float
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def create_task_group(cls) -> TaskGroup:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def create_event(cls) -> Event:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def create_lock(cls, *, fast_acquire: bool) -> Lock:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def create_semaphore(
|
||||||
|
cls,
|
||||||
|
initial_value: int,
|
||||||
|
*,
|
||||||
|
max_value: int | None = None,
|
||||||
|
fast_acquire: bool = False,
|
||||||
|
) -> Semaphore:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def create_capacity_limiter(cls, total_tokens: float) -> CapacityLimiter:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def run_sync_in_worker_thread(
|
||||||
|
cls,
|
||||||
|
func: Callable[[Unpack[PosArgsT]], T_Retval],
|
||||||
|
args: tuple[Unpack[PosArgsT]],
|
||||||
|
abandon_on_cancel: bool = False,
|
||||||
|
limiter: CapacityLimiter | None = None,
|
||||||
|
) -> T_Retval:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def check_cancelled(cls) -> None:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def run_async_from_thread(
|
||||||
|
cls,
|
||||||
|
func: Callable[[Unpack[PosArgsT]], Coroutine[Any, Any, T_co]],
|
||||||
|
args: tuple[Unpack[PosArgsT]],
|
||||||
|
token: object,
|
||||||
|
) -> T_co:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def run_sync_from_thread(
|
||||||
|
cls,
|
||||||
|
func: Callable[[Unpack[PosArgsT]], T_Retval],
|
||||||
|
args: tuple[Unpack[PosArgsT]],
|
||||||
|
token: object,
|
||||||
|
) -> T_Retval:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def open_process(
|
||||||
|
cls,
|
||||||
|
command: StrOrBytesPath | Sequence[StrOrBytesPath],
|
||||||
|
*,
|
||||||
|
stdin: int | IO[Any] | None,
|
||||||
|
stdout: int | IO[Any] | None,
|
||||||
|
stderr: int | IO[Any] | None,
|
||||||
|
cwd: StrOrBytesPath | None = None,
|
||||||
|
env: Mapping[str, str] | None = None,
|
||||||
|
startupinfo: Any = None,
|
||||||
|
creationflags: int = 0,
|
||||||
|
start_new_session: bool = False,
|
||||||
|
pass_fds: Sequence[int] = (),
|
||||||
|
user: str | int | None = None,
|
||||||
|
group: str | int | None = None,
|
||||||
|
extra_groups: Iterable[str | int] | None = None,
|
||||||
|
umask: int = -1,
|
||||||
|
**kwargs: Any,
|
||||||
|
) -> Process:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def setup_process_pool_exit_at_shutdown(cls, workers: set[Process]) -> None:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def connect_tcp(
|
||||||
|
cls, host: str, port: int, local_address: IPSockAddrType | None = None
|
||||||
|
) -> SocketStream:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def connect_unix(cls, path: str | bytes) -> UNIXSocketStream:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def create_tcp_listener(cls, sock: socket) -> SocketListener:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def create_unix_listener(cls, sock: socket) -> SocketListener:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def create_udp_socket(
|
||||||
|
cls,
|
||||||
|
family: AddressFamily,
|
||||||
|
local_address: IPSockAddrType | None,
|
||||||
|
remote_address: IPSockAddrType | None,
|
||||||
|
reuse_port: bool,
|
||||||
|
) -> UDPSocket | ConnectedUDPSocket:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@overload
|
||||||
|
async def create_unix_datagram_socket(
|
||||||
|
cls, raw_socket: socket, remote_path: None
|
||||||
|
) -> UNIXDatagramSocket: ...
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@overload
|
||||||
|
async def create_unix_datagram_socket(
|
||||||
|
cls, raw_socket: socket, remote_path: str | bytes
|
||||||
|
) -> ConnectedUNIXDatagramSocket: ...
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def create_unix_datagram_socket(
|
||||||
|
cls, raw_socket: socket, remote_path: str | bytes | None
|
||||||
|
) -> UNIXDatagramSocket | ConnectedUNIXDatagramSocket:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def getaddrinfo(
|
||||||
|
cls,
|
||||||
|
host: bytes | str | None,
|
||||||
|
port: str | int | None,
|
||||||
|
*,
|
||||||
|
family: int | AddressFamily = 0,
|
||||||
|
type: int | SocketKind = 0,
|
||||||
|
proto: int = 0,
|
||||||
|
flags: int = 0,
|
||||||
|
) -> Sequence[
|
||||||
|
tuple[
|
||||||
|
AddressFamily,
|
||||||
|
SocketKind,
|
||||||
|
int,
|
||||||
|
str,
|
||||||
|
tuple[str, int] | tuple[str, int, int, int] | tuple[int, bytes],
|
||||||
|
]
|
||||||
|
]:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def getnameinfo(
|
||||||
|
cls, sockaddr: IPSockAddrType, flags: int = 0
|
||||||
|
) -> tuple[str, str]:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def wait_readable(cls, obj: FileDescriptorLike) -> None:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def wait_writable(cls, obj: FileDescriptorLike) -> None:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def notify_closing(cls, obj: FileDescriptorLike) -> None:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def wrap_listener_socket(cls, sock: socket) -> SocketListener:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def wrap_stream_socket(cls, sock: socket) -> SocketStream:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def wrap_unix_stream_socket(cls, sock: socket) -> UNIXSocketStream:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def wrap_udp_socket(cls, sock: socket) -> UDPSocket:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def wrap_connected_udp_socket(cls, sock: socket) -> ConnectedUDPSocket:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def wrap_unix_datagram_socket(cls, sock: socket) -> UNIXDatagramSocket:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def wrap_connected_unix_datagram_socket(
|
||||||
|
cls, sock: socket
|
||||||
|
) -> ConnectedUNIXDatagramSocket:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def current_default_thread_limiter(cls) -> CapacityLimiter:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def open_signal_receiver(
|
||||||
|
cls, *signals: Signals
|
||||||
|
) -> AbstractContextManager[AsyncIterator[Signals]]:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def get_current_task(cls) -> TaskInfo:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def get_running_tasks(cls) -> Sequence[TaskInfo]:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
async def wait_all_tasks_blocked(cls) -> None:
|
||||||
|
pass
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
@abstractmethod
|
||||||
|
def create_test_runner(cls, options: dict[str, Any]) -> TestRunner:
|
||||||
|
pass
|
||||||
@@ -0,0 +1,39 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import sys
|
||||||
|
from abc import ABCMeta, abstractmethod
|
||||||
|
from types import TracebackType
|
||||||
|
from typing import TypeVar
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import Self
|
||||||
|
else:
|
||||||
|
from typing_extensions import Self
|
||||||
|
|
||||||
|
T = TypeVar("T")
|
||||||
|
|
||||||
|
|
||||||
|
class AsyncResource(metaclass=ABCMeta):
|
||||||
|
"""
|
||||||
|
Abstract base class for all closeable asynchronous resources.
|
||||||
|
|
||||||
|
Works as an asynchronous context manager which returns the instance itself on enter,
|
||||||
|
and calls :meth:`aclose` on exit.
|
||||||
|
"""
|
||||||
|
|
||||||
|
__slots__ = ()
|
||||||
|
|
||||||
|
async def __aenter__(self) -> Self:
|
||||||
|
return self
|
||||||
|
|
||||||
|
async def __aexit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
await self.aclose()
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
"""Close the resource."""
|
||||||
@@ -0,0 +1,401 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import errno
|
||||||
|
import socket
|
||||||
|
from abc import abstractmethod
|
||||||
|
from collections.abc import Callable, Collection, Mapping
|
||||||
|
from contextlib import AsyncExitStack
|
||||||
|
from io import IOBase
|
||||||
|
from ipaddress import IPv4Address, IPv6Address
|
||||||
|
from socket import AddressFamily
|
||||||
|
from typing import TYPE_CHECKING, Any, TypeAlias, TypeVar
|
||||||
|
|
||||||
|
from .._core._eventloop import get_async_backend
|
||||||
|
from .._core._typedattr import (
|
||||||
|
TypedAttributeProvider,
|
||||||
|
TypedAttributeSet,
|
||||||
|
typed_attribute,
|
||||||
|
)
|
||||||
|
from ._streams import ByteStream, Listener, UnreliableObjectStream
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
from ._tasks import TaskGroup
|
||||||
|
|
||||||
|
IPAddressType: TypeAlias = str | IPv4Address | IPv6Address
|
||||||
|
IPSockAddrType: TypeAlias = tuple[str, int]
|
||||||
|
SockAddrType: TypeAlias = IPSockAddrType | str
|
||||||
|
UDPPacketType: TypeAlias = tuple[bytes, IPSockAddrType]
|
||||||
|
UNIXDatagramPacketType: TypeAlias = tuple[bytes, str]
|
||||||
|
T_Retval = TypeVar("T_Retval")
|
||||||
|
|
||||||
|
|
||||||
|
def _validate_socket(
|
||||||
|
sock_or_fd: socket.socket | int,
|
||||||
|
sock_type: socket.SocketKind,
|
||||||
|
addr_family: socket.AddressFamily = socket.AF_UNSPEC,
|
||||||
|
*,
|
||||||
|
require_connected: bool = False,
|
||||||
|
require_bound: bool = False,
|
||||||
|
) -> socket.socket:
|
||||||
|
if isinstance(sock_or_fd, int):
|
||||||
|
try:
|
||||||
|
sock = socket.socket(fileno=sock_or_fd)
|
||||||
|
except OSError as exc:
|
||||||
|
if exc.errno == errno.ENOTSOCK:
|
||||||
|
raise ValueError(
|
||||||
|
"the file descriptor does not refer to a socket"
|
||||||
|
) from exc
|
||||||
|
elif require_connected:
|
||||||
|
raise ValueError("the socket must be connected") from exc
|
||||||
|
elif require_bound:
|
||||||
|
raise ValueError("the socket must be bound to a local address") from exc
|
||||||
|
else:
|
||||||
|
raise
|
||||||
|
elif isinstance(sock_or_fd, socket.socket):
|
||||||
|
sock = sock_or_fd
|
||||||
|
else:
|
||||||
|
raise TypeError(
|
||||||
|
f"expected an int or socket, got {type(sock_or_fd).__qualname__} instead"
|
||||||
|
)
|
||||||
|
|
||||||
|
try:
|
||||||
|
if require_connected:
|
||||||
|
try:
|
||||||
|
sock.getpeername()
|
||||||
|
except OSError as exc:
|
||||||
|
raise ValueError("the socket must be connected") from exc
|
||||||
|
|
||||||
|
if require_bound:
|
||||||
|
try:
|
||||||
|
if sock.family in (socket.AF_INET, socket.AF_INET6):
|
||||||
|
bound_addr = sock.getsockname()[1]
|
||||||
|
else:
|
||||||
|
bound_addr = sock.getsockname()
|
||||||
|
except OSError:
|
||||||
|
bound_addr = None
|
||||||
|
|
||||||
|
if not bound_addr:
|
||||||
|
raise ValueError("the socket must be bound to a local address")
|
||||||
|
|
||||||
|
if addr_family != socket.AF_UNSPEC and sock.family != addr_family:
|
||||||
|
raise ValueError(
|
||||||
|
f"address family mismatch: expected {addr_family.name}, got "
|
||||||
|
f"{sock.family.name}"
|
||||||
|
)
|
||||||
|
|
||||||
|
if sock.type != sock_type:
|
||||||
|
raise ValueError(
|
||||||
|
f"socket type mismatch: expected {sock_type.name}, got {sock.type.name}"
|
||||||
|
)
|
||||||
|
except BaseException:
|
||||||
|
# Avoid ResourceWarning from the locally constructed socket object
|
||||||
|
if isinstance(sock_or_fd, int):
|
||||||
|
sock.detach()
|
||||||
|
|
||||||
|
raise
|
||||||
|
|
||||||
|
sock.setblocking(False)
|
||||||
|
return sock
|
||||||
|
|
||||||
|
|
||||||
|
class SocketAttribute(TypedAttributeSet):
|
||||||
|
"""
|
||||||
|
.. attribute:: family
|
||||||
|
:type: socket.AddressFamily
|
||||||
|
|
||||||
|
the address family of the underlying socket
|
||||||
|
|
||||||
|
.. attribute:: local_address
|
||||||
|
:type: tuple[str, int] | str
|
||||||
|
|
||||||
|
the local address the underlying socket is connected to
|
||||||
|
|
||||||
|
.. attribute:: local_port
|
||||||
|
:type: int
|
||||||
|
|
||||||
|
for IP based sockets, the local port the underlying socket is bound to
|
||||||
|
|
||||||
|
.. attribute:: raw_socket
|
||||||
|
:type: socket.socket
|
||||||
|
|
||||||
|
the underlying stdlib socket object
|
||||||
|
|
||||||
|
.. attribute:: remote_address
|
||||||
|
:type: tuple[str, int] | str
|
||||||
|
|
||||||
|
the remote address the underlying socket is connected to
|
||||||
|
|
||||||
|
.. attribute:: remote_port
|
||||||
|
:type: int
|
||||||
|
|
||||||
|
for IP based sockets, the remote port the underlying socket is connected to
|
||||||
|
"""
|
||||||
|
|
||||||
|
family: AddressFamily = typed_attribute()
|
||||||
|
local_address: SockAddrType = typed_attribute()
|
||||||
|
local_port: int = typed_attribute()
|
||||||
|
raw_socket: socket.socket = typed_attribute()
|
||||||
|
remote_address: SockAddrType = typed_attribute()
|
||||||
|
remote_port: int = typed_attribute()
|
||||||
|
|
||||||
|
|
||||||
|
class _SocketProvider(TypedAttributeProvider):
|
||||||
|
@property
|
||||||
|
def extra_attributes(self) -> Mapping[Any, Callable[[], Any]]:
|
||||||
|
from .._core._sockets import convert_ipv6_sockaddr as convert
|
||||||
|
|
||||||
|
attributes: dict[Any, Callable[[], Any]] = {
|
||||||
|
SocketAttribute.family: lambda: self._raw_socket.family,
|
||||||
|
SocketAttribute.local_address: lambda: convert(
|
||||||
|
self._raw_socket.getsockname()
|
||||||
|
),
|
||||||
|
SocketAttribute.raw_socket: lambda: self._raw_socket,
|
||||||
|
}
|
||||||
|
try:
|
||||||
|
peername: tuple[str, int] | None = convert(self._raw_socket.getpeername())
|
||||||
|
except OSError:
|
||||||
|
peername = None
|
||||||
|
|
||||||
|
# Provide the remote address for connected sockets
|
||||||
|
if peername is not None:
|
||||||
|
attributes[SocketAttribute.remote_address] = lambda: peername
|
||||||
|
|
||||||
|
# Provide local and remote ports for IP based sockets
|
||||||
|
if self._raw_socket.family in (AddressFamily.AF_INET, AddressFamily.AF_INET6):
|
||||||
|
attributes[SocketAttribute.local_port] = lambda: (
|
||||||
|
self._raw_socket.getsockname()[1]
|
||||||
|
)
|
||||||
|
if peername is not None:
|
||||||
|
remote_port = peername[1]
|
||||||
|
attributes[SocketAttribute.remote_port] = lambda: remote_port
|
||||||
|
|
||||||
|
return attributes
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def _raw_socket(self) -> socket.socket:
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
class SocketStream(ByteStream, _SocketProvider):
|
||||||
|
"""
|
||||||
|
Transports bytes over a socket.
|
||||||
|
|
||||||
|
Supports all relevant extra attributes from :class:`~SocketAttribute`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
async def from_socket(cls, sock_or_fd: socket.socket | int) -> SocketStream:
|
||||||
|
"""
|
||||||
|
Wrap an existing socket object or file descriptor as a socket stream.
|
||||||
|
|
||||||
|
The newly created socket wrapper takes ownership of the socket being passed in.
|
||||||
|
The existing socket must already be connected.
|
||||||
|
|
||||||
|
:param sock_or_fd: a socket object or file descriptor
|
||||||
|
:return: a socket stream
|
||||||
|
|
||||||
|
"""
|
||||||
|
sock = _validate_socket(sock_or_fd, socket.SOCK_STREAM, require_connected=True)
|
||||||
|
return await get_async_backend().wrap_stream_socket(sock)
|
||||||
|
|
||||||
|
|
||||||
|
class UNIXSocketStream(SocketStream):
|
||||||
|
@classmethod
|
||||||
|
async def from_socket(cls, sock_or_fd: socket.socket | int) -> UNIXSocketStream:
|
||||||
|
"""
|
||||||
|
Wrap an existing socket object or file descriptor as a UNIX socket stream.
|
||||||
|
|
||||||
|
The newly created socket wrapper takes ownership of the socket being passed in.
|
||||||
|
The existing socket must already be connected.
|
||||||
|
|
||||||
|
:param sock_or_fd: a socket object or file descriptor
|
||||||
|
:return: a UNIX socket stream
|
||||||
|
|
||||||
|
"""
|
||||||
|
sock = _validate_socket(
|
||||||
|
sock_or_fd, socket.SOCK_STREAM, socket.AF_UNIX, require_connected=True
|
||||||
|
)
|
||||||
|
return await get_async_backend().wrap_unix_stream_socket(sock)
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def send_fds(self, message: bytes, fds: Collection[int | IOBase]) -> None:
|
||||||
|
"""
|
||||||
|
Send file descriptors along with a message to the peer.
|
||||||
|
|
||||||
|
:param message: a non-empty bytestring
|
||||||
|
:param fds: a collection of files (either numeric file descriptors or open file
|
||||||
|
or socket objects)
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def receive_fds(self, msglen: int, maxfds: int) -> tuple[bytes, list[int]]:
|
||||||
|
"""
|
||||||
|
Receive file descriptors along with a message from the peer.
|
||||||
|
|
||||||
|
:param msglen: length of the message to expect from the peer
|
||||||
|
:param maxfds: maximum number of file descriptors to expect from the peer
|
||||||
|
:return: a tuple of (message, file descriptors)
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class SocketListener(Listener[SocketStream], _SocketProvider):
|
||||||
|
"""
|
||||||
|
Listens to incoming socket connections.
|
||||||
|
|
||||||
|
Supports all relevant extra attributes from :class:`~SocketAttribute`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
async def from_socket(
|
||||||
|
cls,
|
||||||
|
sock_or_fd: socket.socket | int,
|
||||||
|
) -> SocketListener:
|
||||||
|
"""
|
||||||
|
Wrap an existing socket object or file descriptor as a socket listener.
|
||||||
|
|
||||||
|
The newly created listener takes ownership of the socket being passed in.
|
||||||
|
|
||||||
|
:param sock_or_fd: a socket object or file descriptor
|
||||||
|
:return: a socket listener
|
||||||
|
|
||||||
|
"""
|
||||||
|
sock = _validate_socket(sock_or_fd, socket.SOCK_STREAM, require_bound=True)
|
||||||
|
return await get_async_backend().wrap_listener_socket(sock)
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def accept(self) -> SocketStream:
|
||||||
|
"""Accept an incoming connection."""
|
||||||
|
|
||||||
|
async def serve(
|
||||||
|
self,
|
||||||
|
handler: Callable[[SocketStream], Any],
|
||||||
|
task_group: TaskGroup | None = None,
|
||||||
|
) -> None:
|
||||||
|
from .. import create_task_group
|
||||||
|
|
||||||
|
async with AsyncExitStack() as stack:
|
||||||
|
if task_group is None:
|
||||||
|
task_group = await stack.enter_async_context(create_task_group())
|
||||||
|
|
||||||
|
while True:
|
||||||
|
stream = await self.accept()
|
||||||
|
task_group.start_soon(handler, stream)
|
||||||
|
|
||||||
|
|
||||||
|
class UDPSocket(UnreliableObjectStream[UDPPacketType], _SocketProvider):
|
||||||
|
"""
|
||||||
|
Represents an unconnected UDP socket.
|
||||||
|
|
||||||
|
Supports all relevant extra attributes from :class:`~SocketAttribute`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
async def from_socket(cls, sock_or_fd: socket.socket | int) -> UDPSocket:
|
||||||
|
"""
|
||||||
|
Wrap an existing socket object or file descriptor as a UDP socket.
|
||||||
|
|
||||||
|
The newly created socket wrapper takes ownership of the socket being passed in.
|
||||||
|
The existing socket must be bound to a local address.
|
||||||
|
|
||||||
|
:param sock_or_fd: a socket object or file descriptor
|
||||||
|
:return: a UDP socket
|
||||||
|
|
||||||
|
"""
|
||||||
|
sock = _validate_socket(sock_or_fd, socket.SOCK_DGRAM, require_bound=True)
|
||||||
|
return await get_async_backend().wrap_udp_socket(sock)
|
||||||
|
|
||||||
|
async def sendto(self, data: bytes, host: str, port: int) -> None:
|
||||||
|
"""
|
||||||
|
Alias for :meth:`~.UnreliableObjectSendStream.send` ((data, (host, port))).
|
||||||
|
|
||||||
|
"""
|
||||||
|
return await self.send((data, (host, port)))
|
||||||
|
|
||||||
|
|
||||||
|
class ConnectedUDPSocket(UnreliableObjectStream[bytes], _SocketProvider):
|
||||||
|
"""
|
||||||
|
Represents an connected UDP socket.
|
||||||
|
|
||||||
|
Supports all relevant extra attributes from :class:`~SocketAttribute`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
async def from_socket(cls, sock_or_fd: socket.socket | int) -> ConnectedUDPSocket:
|
||||||
|
"""
|
||||||
|
Wrap an existing socket object or file descriptor as a connected UDP socket.
|
||||||
|
|
||||||
|
The newly created socket wrapper takes ownership of the socket being passed in.
|
||||||
|
The existing socket must already be connected.
|
||||||
|
|
||||||
|
:param sock_or_fd: a socket object or file descriptor
|
||||||
|
:return: a connected UDP socket
|
||||||
|
|
||||||
|
"""
|
||||||
|
sock = _validate_socket(
|
||||||
|
sock_or_fd,
|
||||||
|
socket.SOCK_DGRAM,
|
||||||
|
require_connected=True,
|
||||||
|
)
|
||||||
|
return await get_async_backend().wrap_connected_udp_socket(sock)
|
||||||
|
|
||||||
|
|
||||||
|
class UNIXDatagramSocket(
|
||||||
|
UnreliableObjectStream[UNIXDatagramPacketType], _SocketProvider
|
||||||
|
):
|
||||||
|
"""
|
||||||
|
Represents an unconnected Unix datagram socket.
|
||||||
|
|
||||||
|
Supports all relevant extra attributes from :class:`~SocketAttribute`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
async def from_socket(
|
||||||
|
cls,
|
||||||
|
sock_or_fd: socket.socket | int,
|
||||||
|
) -> UNIXDatagramSocket:
|
||||||
|
"""
|
||||||
|
Wrap an existing socket object or file descriptor as a UNIX datagram
|
||||||
|
socket.
|
||||||
|
|
||||||
|
The newly created socket wrapper takes ownership of the socket being passed in.
|
||||||
|
|
||||||
|
:param sock_or_fd: a socket object or file descriptor
|
||||||
|
:return: a UNIX datagram socket
|
||||||
|
|
||||||
|
"""
|
||||||
|
sock = _validate_socket(sock_or_fd, socket.SOCK_DGRAM, socket.AF_UNIX)
|
||||||
|
return await get_async_backend().wrap_unix_datagram_socket(sock)
|
||||||
|
|
||||||
|
async def sendto(self, data: bytes, path: str) -> None:
|
||||||
|
"""Alias for :meth:`~.UnreliableObjectSendStream.send` ((data, path))."""
|
||||||
|
return await self.send((data, path))
|
||||||
|
|
||||||
|
|
||||||
|
class ConnectedUNIXDatagramSocket(UnreliableObjectStream[bytes], _SocketProvider):
|
||||||
|
"""
|
||||||
|
Represents a connected Unix datagram socket.
|
||||||
|
|
||||||
|
Supports all relevant extra attributes from :class:`~SocketAttribute`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
async def from_socket(
|
||||||
|
cls,
|
||||||
|
sock_or_fd: socket.socket | int,
|
||||||
|
) -> ConnectedUNIXDatagramSocket:
|
||||||
|
"""
|
||||||
|
Wrap an existing socket object or file descriptor as a connected UNIX datagram
|
||||||
|
socket.
|
||||||
|
|
||||||
|
The newly created socket wrapper takes ownership of the socket being passed in.
|
||||||
|
The existing socket must already be connected.
|
||||||
|
|
||||||
|
:param sock_or_fd: a socket object or file descriptor
|
||||||
|
:return: a connected UNIX datagram socket
|
||||||
|
|
||||||
|
"""
|
||||||
|
sock = _validate_socket(
|
||||||
|
sock_or_fd, socket.SOCK_DGRAM, socket.AF_UNIX, require_connected=True
|
||||||
|
)
|
||||||
|
return await get_async_backend().wrap_connected_unix_datagram_socket(sock)
|
||||||
@@ -0,0 +1,237 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from abc import ABCMeta, abstractmethod
|
||||||
|
from collections.abc import Callable
|
||||||
|
from typing import TYPE_CHECKING, Any, Generic, TypeAlias, TypeVar
|
||||||
|
|
||||||
|
from .._core._exceptions import EndOfStream
|
||||||
|
from .._core._typedattr import TypedAttributeProvider
|
||||||
|
from ._resources import AsyncResource
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
from ._tasks import TaskGroup
|
||||||
|
|
||||||
|
T_Item = TypeVar("T_Item")
|
||||||
|
T_co = TypeVar("T_co", covariant=True)
|
||||||
|
T_contra = TypeVar("T_contra", contravariant=True)
|
||||||
|
|
||||||
|
|
||||||
|
class UnreliableObjectReceiveStream(
|
||||||
|
AsyncResource, TypedAttributeProvider, Generic[T_co]
|
||||||
|
):
|
||||||
|
"""
|
||||||
|
An interface for receiving objects.
|
||||||
|
|
||||||
|
This interface makes no guarantees that the received messages arrive in the order in
|
||||||
|
which they were sent, or that no messages are missed.
|
||||||
|
|
||||||
|
Asynchronously iterating over objects of this type will yield objects matching the
|
||||||
|
given type parameter.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __aiter__(self) -> UnreliableObjectReceiveStream[T_co]:
|
||||||
|
return self
|
||||||
|
|
||||||
|
async def __anext__(self) -> T_co:
|
||||||
|
try:
|
||||||
|
return await self.receive()
|
||||||
|
except EndOfStream:
|
||||||
|
raise StopAsyncIteration from None
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def receive(self) -> T_co:
|
||||||
|
"""
|
||||||
|
Receive the next item.
|
||||||
|
|
||||||
|
:raises ~anyio.ClosedResourceError: if the receive stream has been explicitly
|
||||||
|
closed
|
||||||
|
:raises ~anyio.EndOfStream: if this stream has been closed from the other end
|
||||||
|
:raises ~anyio.BrokenResourceError: if this stream has been rendered unusable
|
||||||
|
due to external causes
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class UnreliableObjectSendStream(
|
||||||
|
AsyncResource, TypedAttributeProvider, Generic[T_contra]
|
||||||
|
):
|
||||||
|
"""
|
||||||
|
An interface for sending objects.
|
||||||
|
|
||||||
|
This interface makes no guarantees that the messages sent will reach the
|
||||||
|
recipient(s) in the same order in which they were sent, or at all.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def send(self, item: T_contra) -> None:
|
||||||
|
"""
|
||||||
|
Send an item to the peer(s).
|
||||||
|
|
||||||
|
:param item: the item to send
|
||||||
|
:raises ~anyio.ClosedResourceError: if the send stream has been explicitly
|
||||||
|
closed
|
||||||
|
:raises ~anyio.BrokenResourceError: if this stream has been rendered unusable
|
||||||
|
due to external causes
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class UnreliableObjectStream(
|
||||||
|
UnreliableObjectReceiveStream[T_Item], UnreliableObjectSendStream[T_Item]
|
||||||
|
):
|
||||||
|
"""
|
||||||
|
A bidirectional message stream which does not guarantee the order or reliability of
|
||||||
|
message delivery.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class ObjectReceiveStream(UnreliableObjectReceiveStream[T_co]):
|
||||||
|
"""
|
||||||
|
A receive message stream which guarantees that messages are received in the same
|
||||||
|
order in which they were sent, and that no messages are missed.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class ObjectSendStream(UnreliableObjectSendStream[T_contra]):
|
||||||
|
"""
|
||||||
|
A send message stream which guarantees that messages are delivered in the same order
|
||||||
|
in which they were sent, without missing any messages in the middle.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class ObjectStream(
|
||||||
|
ObjectReceiveStream[T_Item],
|
||||||
|
ObjectSendStream[T_Item],
|
||||||
|
UnreliableObjectStream[T_Item],
|
||||||
|
):
|
||||||
|
"""
|
||||||
|
A bidirectional message stream which guarantees the order and reliability of message
|
||||||
|
delivery.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def send_eof(self) -> None:
|
||||||
|
"""
|
||||||
|
Send an end-of-file indication to the peer.
|
||||||
|
|
||||||
|
You should not try to send any further data to this stream after calling this
|
||||||
|
method. This method is idempotent (does nothing on successive calls).
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class ByteReceiveStream(AsyncResource, TypedAttributeProvider):
|
||||||
|
"""
|
||||||
|
An interface for receiving bytes from a single peer.
|
||||||
|
|
||||||
|
Iterating this byte stream will yield a byte string of arbitrary length, but no more
|
||||||
|
than 65536 bytes.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __aiter__(self) -> ByteReceiveStream:
|
||||||
|
return self
|
||||||
|
|
||||||
|
async def __anext__(self) -> bytes:
|
||||||
|
try:
|
||||||
|
return await self.receive()
|
||||||
|
except EndOfStream:
|
||||||
|
raise StopAsyncIteration from None
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def receive(self, max_bytes: int = 65536) -> bytes:
|
||||||
|
"""
|
||||||
|
Receive at most ``max_bytes`` bytes from the peer.
|
||||||
|
|
||||||
|
.. note:: Implementers of this interface should not return an empty
|
||||||
|
:class:`bytes` object, and users should ignore them.
|
||||||
|
|
||||||
|
:param max_bytes: maximum number of bytes to receive (must be a positive
|
||||||
|
integer)
|
||||||
|
:return: the received bytes
|
||||||
|
:raises ValueError: if ``max_bytes`` is less than 1
|
||||||
|
:raises ~anyio.EndOfStream: if this stream has been closed from the other end
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class ByteSendStream(AsyncResource, TypedAttributeProvider):
|
||||||
|
"""An interface for sending bytes to a single peer."""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def send(self, item: bytes) -> None:
|
||||||
|
"""
|
||||||
|
Send the given bytes to the peer.
|
||||||
|
|
||||||
|
:param item: the bytes to send
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class ByteStream(ByteReceiveStream, ByteSendStream):
|
||||||
|
"""A bidirectional byte stream."""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def send_eof(self) -> None:
|
||||||
|
"""
|
||||||
|
Send an end-of-file indication to the peer.
|
||||||
|
|
||||||
|
You should not try to send any further data to this stream after calling this
|
||||||
|
method. This method is idempotent (does nothing on successive calls).
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
#: Type alias for all unreliable bytes-oriented receive streams.
|
||||||
|
AnyUnreliableByteReceiveStream: TypeAlias = (
|
||||||
|
UnreliableObjectReceiveStream[bytes] | ByteReceiveStream
|
||||||
|
)
|
||||||
|
#: Type alias for all unreliable bytes-oriented send streams.
|
||||||
|
AnyUnreliableByteSendStream: TypeAlias = (
|
||||||
|
UnreliableObjectSendStream[bytes] | ByteSendStream
|
||||||
|
)
|
||||||
|
#: Type alias for all unreliable bytes-oriented streams.
|
||||||
|
AnyUnreliableByteStream: TypeAlias = UnreliableObjectStream[bytes] | ByteStream
|
||||||
|
#: Type alias for all bytes-oriented receive streams.
|
||||||
|
AnyByteReceiveStream: TypeAlias = ObjectReceiveStream[bytes] | ByteReceiveStream
|
||||||
|
#: Type alias for all bytes-oriented send streams.
|
||||||
|
AnyByteSendStream: TypeAlias = ObjectSendStream[bytes] | ByteSendStream
|
||||||
|
#: Type alias for all bytes-oriented streams.
|
||||||
|
AnyByteStream: TypeAlias = ObjectStream[bytes] | ByteStream
|
||||||
|
|
||||||
|
|
||||||
|
class Listener(AsyncResource, TypedAttributeProvider, Generic[T_co]):
|
||||||
|
"""An interface for objects that let you accept incoming connections."""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def serve(
|
||||||
|
self, handler: Callable[[T_co], Any], task_group: TaskGroup | None = None
|
||||||
|
) -> None:
|
||||||
|
"""
|
||||||
|
Accept incoming connections as they come in and start tasks to handle them.
|
||||||
|
|
||||||
|
:param handler: a callable that will be used to handle each accepted connection
|
||||||
|
:param task_group: the task group that will be used to start tasks for handling
|
||||||
|
each accepted connection (if omitted, an ad-hoc task group will be created)
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class ObjectStreamConnectable(Generic[T_co], metaclass=ABCMeta):
|
||||||
|
@abstractmethod
|
||||||
|
async def connect(self) -> ObjectStream[T_co]:
|
||||||
|
"""
|
||||||
|
Connect to the remote endpoint.
|
||||||
|
|
||||||
|
:return: an object stream connected to the remote end
|
||||||
|
:raises ConnectionFailed: if the connection fails
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class ByteStreamConnectable(metaclass=ABCMeta):
|
||||||
|
@abstractmethod
|
||||||
|
async def connect(self) -> ByteStream:
|
||||||
|
"""
|
||||||
|
Connect to the remote endpoint.
|
||||||
|
|
||||||
|
:return: a bytestream connected to the remote end
|
||||||
|
:raises ConnectionFailed: if the connection fails
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
#: Type alias for all connectables returning bytestreams or bytes-oriented object streams
|
||||||
|
AnyByteStreamConnectable: TypeAlias = (
|
||||||
|
ObjectStreamConnectable[bytes] | ByteStreamConnectable
|
||||||
|
)
|
||||||
@@ -0,0 +1,82 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from abc import abstractmethod
|
||||||
|
from signal import Signals
|
||||||
|
from typing import TYPE_CHECKING
|
||||||
|
|
||||||
|
from ._resources import AsyncResource
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
from ._streams import ByteReceiveStream, ByteSendStream
|
||||||
|
|
||||||
|
|
||||||
|
class Process(AsyncResource):
|
||||||
|
"""An asynchronous version of :class:`subprocess.Popen`."""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def wait(self) -> int:
|
||||||
|
"""
|
||||||
|
Wait until the process exits.
|
||||||
|
|
||||||
|
:return: the exit code of the process
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
def terminate(self) -> None:
|
||||||
|
"""
|
||||||
|
Terminates the process, gracefully if possible.
|
||||||
|
|
||||||
|
On Windows, this calls ``TerminateProcess()``.
|
||||||
|
On POSIX systems, this sends ``SIGTERM`` to the process.
|
||||||
|
|
||||||
|
.. seealso:: :meth:`subprocess.Popen.terminate`
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
def kill(self) -> None:
|
||||||
|
"""
|
||||||
|
Kills the process.
|
||||||
|
|
||||||
|
On Windows, this calls ``TerminateProcess()``.
|
||||||
|
On POSIX systems, this sends ``SIGKILL`` to the process.
|
||||||
|
|
||||||
|
.. seealso:: :meth:`subprocess.Popen.kill`
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
def send_signal(self, signal: Signals) -> None:
|
||||||
|
"""
|
||||||
|
Send a signal to the subprocess.
|
||||||
|
|
||||||
|
.. seealso:: :meth:`subprocess.Popen.send_signal`
|
||||||
|
|
||||||
|
:param signal: the signal number (e.g. :data:`signal.SIGHUP`)
|
||||||
|
"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def pid(self) -> int:
|
||||||
|
"""The process ID of the process."""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def returncode(self) -> int | None:
|
||||||
|
"""
|
||||||
|
The return code of the process. If the process has not yet terminated, this will
|
||||||
|
be ``None``.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def stdin(self) -> ByteSendStream | None:
|
||||||
|
"""The stream for the standard input of the process."""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def stdout(self) -> ByteReceiveStream | None:
|
||||||
|
"""The stream for the standard output of the process."""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def stderr(self) -> ByteReceiveStream | None:
|
||||||
|
"""The stream for the standard error output of the process."""
|
||||||
@@ -0,0 +1,223 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import sys
|
||||||
|
from abc import ABCMeta, abstractmethod
|
||||||
|
from collections.abc import Callable, Coroutine
|
||||||
|
from contextvars import Context
|
||||||
|
from types import TracebackType
|
||||||
|
from typing import TYPE_CHECKING, Any, Literal, Protocol, final, overload
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 13):
|
||||||
|
from typing import TypeVar
|
||||||
|
else:
|
||||||
|
from typing_extensions import TypeVar
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import TypeVarTuple, Unpack
|
||||||
|
else:
|
||||||
|
from typing_extensions import TypeVarTuple, Unpack
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
from .._core._tasks import CancelScope, TaskHandle
|
||||||
|
|
||||||
|
T_co = TypeVar("T_co", covariant=True)
|
||||||
|
T_contra = TypeVar("T_contra", contravariant=True, default=None)
|
||||||
|
PosArgsT = TypeVarTuple("PosArgsT")
|
||||||
|
|
||||||
|
|
||||||
|
def get_coro_name(coro: Coroutine[Any, Any, object], override: object = None) -> str:
|
||||||
|
if override is not None:
|
||||||
|
return str(override)
|
||||||
|
|
||||||
|
try:
|
||||||
|
cr_frame = coro.cr_frame # type: ignore[attr-defined]
|
||||||
|
module = cr_frame.f_globals["__name__"]
|
||||||
|
except (AttributeError, KeyError):
|
||||||
|
module = None
|
||||||
|
|
||||||
|
qualname = getattr(coro, "__qualname__", None)
|
||||||
|
return ".".join([x for x in (module, qualname) if x])
|
||||||
|
|
||||||
|
|
||||||
|
def get_callable_name(func: Callable, override: object = None) -> str:
|
||||||
|
if override is not None:
|
||||||
|
return str(override)
|
||||||
|
|
||||||
|
module = getattr(func, "__module__", None)
|
||||||
|
qualname = getattr(func, "__qualname__", None)
|
||||||
|
return ".".join([x for x in (module, qualname) if x])
|
||||||
|
|
||||||
|
|
||||||
|
def call_for_coroutine(
|
||||||
|
func: Callable[[Unpack[PosArgsT]], Coroutine[Any, Any, T_co]],
|
||||||
|
args: tuple[Unpack[PosArgsT]],
|
||||||
|
**kwargs: Any,
|
||||||
|
) -> Coroutine[Any, Any, T_co]:
|
||||||
|
"""
|
||||||
|
Call the given function with the given positional and keyword arguments.
|
||||||
|
|
||||||
|
:return: the resulting coroutine
|
||||||
|
:raises TypeError: if the return value was not a coroutine object
|
||||||
|
|
||||||
|
"""
|
||||||
|
coro = func(*args, **kwargs)
|
||||||
|
if not isinstance(coro, Coroutine):
|
||||||
|
prefix = f"{func.__module__}." if hasattr(func, "__module__") else ""
|
||||||
|
raise TypeError(
|
||||||
|
f"Expected {prefix}{func.__qualname__}() to return a coroutine, but "
|
||||||
|
f"the return value ({coro!r}) is not a coroutine object"
|
||||||
|
)
|
||||||
|
|
||||||
|
return coro
|
||||||
|
|
||||||
|
|
||||||
|
class TaskStatus(Protocol[T_contra]):
|
||||||
|
@overload
|
||||||
|
def started(self: TaskStatus[None]) -> None: ...
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def started(self, value: T_contra) -> None: ...
|
||||||
|
|
||||||
|
def started(self, value: T_contra | None = None) -> None:
|
||||||
|
"""
|
||||||
|
Signal that the task has started.
|
||||||
|
|
||||||
|
:param value: object passed back to the starter of the task
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class TaskGroup(metaclass=ABCMeta):
|
||||||
|
"""
|
||||||
|
Groups several asynchronous tasks together.
|
||||||
|
|
||||||
|
:ivar cancel_scope: the cancel scope inherited by all child tasks
|
||||||
|
:vartype cancel_scope: CancelScope
|
||||||
|
|
||||||
|
.. note:: On asyncio, support for eager task factories is considered to be
|
||||||
|
**experimental**. In particular, they don't follow the usual semantics of new
|
||||||
|
tasks being scheduled on the next iteration of the event loop, and may thus
|
||||||
|
cause unexpected behavior in code that wasn't written with such semantics in
|
||||||
|
mind.
|
||||||
|
"""
|
||||||
|
|
||||||
|
cancel_scope: CancelScope
|
||||||
|
|
||||||
|
def cancel(self, reason: str | None = None) -> None:
|
||||||
|
"""
|
||||||
|
Cancel this task group's cancel scope immediately.
|
||||||
|
|
||||||
|
This is a shortcut for calling ``.cancel_scope.cancel()`` on the task group.
|
||||||
|
|
||||||
|
:param reason: a message describing the reason for the cancellation
|
||||||
|
|
||||||
|
.. versionadded:: 4.14.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
self.cancel_scope.cancel(reason)
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
def create_task(
|
||||||
|
self,
|
||||||
|
coro: Coroutine[Any, Any, T_co],
|
||||||
|
*,
|
||||||
|
name: object = None,
|
||||||
|
context: Context | None = None,
|
||||||
|
) -> TaskHandle[T_co]:
|
||||||
|
"""
|
||||||
|
Create a new task from a coroutine object and schedule it to run.
|
||||||
|
|
||||||
|
:param coro: a coroutine object
|
||||||
|
:param name: optional name to give the task
|
||||||
|
:param context: optional context to run the task in
|
||||||
|
:return: a task handle
|
||||||
|
|
||||||
|
.. versionadded:: 4.14.0
|
||||||
|
"""
|
||||||
|
|
||||||
|
@final
|
||||||
|
def start_soon(
|
||||||
|
self,
|
||||||
|
func: Callable[[Unpack[PosArgsT]], Coroutine[Any, Any, T_co]],
|
||||||
|
*args: Unpack[PosArgsT],
|
||||||
|
name: object = None,
|
||||||
|
) -> TaskHandle[T_co]:
|
||||||
|
"""
|
||||||
|
Start a new task in this task group.
|
||||||
|
|
||||||
|
:param func: a coroutine function
|
||||||
|
:param args: positional arguments to call the function with
|
||||||
|
:param name: name of the task, for the purposes of introspection and debugging
|
||||||
|
:return: a task handle
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
.. versionchanged:: 4.14.0
|
||||||
|
This method now returns a task handle.
|
||||||
|
|
||||||
|
"""
|
||||||
|
final_name = get_callable_name(func, name)
|
||||||
|
return self.create_task(call_for_coroutine(func, args), name=final_name)
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def start(
|
||||||
|
self,
|
||||||
|
func: Callable[..., Coroutine[Any, Any, T_co]],
|
||||||
|
*args: object,
|
||||||
|
name: object = None,
|
||||||
|
return_handle: Literal[False] = ...,
|
||||||
|
) -> Any: ...
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def start(
|
||||||
|
self,
|
||||||
|
func: Callable[..., Coroutine[Any, Any, T_co]],
|
||||||
|
*args: object,
|
||||||
|
name: object = None,
|
||||||
|
return_handle: Literal[True],
|
||||||
|
) -> TaskHandle[T_co, Any]: ...
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def start(
|
||||||
|
self,
|
||||||
|
func: Callable[..., Coroutine[Any, Any, T_co]],
|
||||||
|
*args: object,
|
||||||
|
name: object = None,
|
||||||
|
return_handle: Literal[False, True] = False,
|
||||||
|
) -> Any:
|
||||||
|
"""
|
||||||
|
Start a new task and wait until it signals for readiness.
|
||||||
|
|
||||||
|
The target callable must accept a keyword argument ``task_status`` (of type
|
||||||
|
:class:`TaskStatus`). Awaiting on this method will return whatever was passed to
|
||||||
|
``task_status.started()`` (``None`` by default).
|
||||||
|
|
||||||
|
.. note:: The :class:`TaskStatus` class is generic, and the type argument should
|
||||||
|
indicate the type of the value that will be passed to
|
||||||
|
``task_status.started()``.
|
||||||
|
|
||||||
|
:param func: a coroutine function that accepts the ``task_status`` keyword
|
||||||
|
argument
|
||||||
|
:param args: positional arguments to call the function with
|
||||||
|
:param name: an optional name for the task, for introspection and debugging
|
||||||
|
:param return_handle: if ``True``, return a :class:`TaskHandle` which also
|
||||||
|
contains the start value in ``start_value``
|
||||||
|
:return: the value passed to ``task_status.started()``
|
||||||
|
:raises RuntimeError: if the task finishes without calling
|
||||||
|
``task_status.started()``
|
||||||
|
|
||||||
|
.. seealso:: :ref:`start_initialize`
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def __aenter__(self) -> TaskGroup:
|
||||||
|
"""Enter the task group context and allow starting new tasks."""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
async def __aexit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> bool:
|
||||||
|
"""Exit the task group context waiting for all tasks to finish."""
|
||||||
@@ -0,0 +1,79 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import sys
|
||||||
|
import types
|
||||||
|
from abc import ABCMeta, abstractmethod
|
||||||
|
from collections.abc import AsyncGenerator, Callable, Coroutine, Iterable
|
||||||
|
from typing import Any, TypeVar
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import Self
|
||||||
|
else:
|
||||||
|
from typing_extensions import Self
|
||||||
|
|
||||||
|
_T = TypeVar("_T")
|
||||||
|
|
||||||
|
|
||||||
|
class TestRunner(metaclass=ABCMeta):
|
||||||
|
"""
|
||||||
|
Encapsulates a running event loop. Every call made through this object will use the
|
||||||
|
same event loop.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __enter__(self) -> Self:
|
||||||
|
return self
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
def __exit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: types.TracebackType | None,
|
||||||
|
) -> bool | None: ...
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
def run_asyncgen_fixture(
|
||||||
|
self,
|
||||||
|
fixture_func: Callable[..., AsyncGenerator[_T, Any]],
|
||||||
|
kwargs: dict[str, Any],
|
||||||
|
) -> Iterable[_T]:
|
||||||
|
"""
|
||||||
|
Run an async generator fixture.
|
||||||
|
|
||||||
|
:param fixture_func: the fixture function
|
||||||
|
:param kwargs: keyword arguments to call the fixture function with
|
||||||
|
:return: an iterator yielding the value yielded from the async generator
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
def run_fixture(
|
||||||
|
self,
|
||||||
|
fixture_func: Callable[..., Coroutine[Any, Any, _T]],
|
||||||
|
kwargs: dict[str, Any],
|
||||||
|
) -> _T:
|
||||||
|
"""
|
||||||
|
Run an async fixture.
|
||||||
|
|
||||||
|
:param fixture_func: the fixture function
|
||||||
|
:param kwargs: keyword arguments to call the fixture function with
|
||||||
|
:return: the return value of the fixture function
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
def run_test(
|
||||||
|
self, test_func: Callable[..., Coroutine[Any, Any, Any]], kwargs: dict[str, Any]
|
||||||
|
) -> None:
|
||||||
|
"""
|
||||||
|
Run an async test function.
|
||||||
|
|
||||||
|
:param test_func: the test function
|
||||||
|
:param kwargs: keyword arguments to call the test function with
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abstractmethod
|
||||||
|
def is_running(self) -> bool:
|
||||||
|
"""
|
||||||
|
Check if the test runner is running.
|
||||||
|
|
||||||
|
:return: ``True`` if the coroutine is currently being run, ``False`` otherwise.
|
||||||
|
"""
|
||||||
@@ -0,0 +1,588 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"BlockingPortal",
|
||||||
|
"BlockingPortalProvider",
|
||||||
|
"check_cancelled",
|
||||||
|
"run",
|
||||||
|
"run_sync",
|
||||||
|
"start_blocking_portal",
|
||||||
|
)
|
||||||
|
|
||||||
|
import sys
|
||||||
|
from collections.abc import Awaitable, Callable, Coroutine, Generator
|
||||||
|
from concurrent.futures import Future
|
||||||
|
from contextlib import (
|
||||||
|
AbstractAsyncContextManager,
|
||||||
|
AbstractContextManager,
|
||||||
|
contextmanager,
|
||||||
|
)
|
||||||
|
from contextvars import Context
|
||||||
|
from dataclasses import dataclass, field
|
||||||
|
from functools import partial
|
||||||
|
from inspect import isawaitable
|
||||||
|
from threading import Lock, Thread, current_thread, get_ident
|
||||||
|
from types import TracebackType
|
||||||
|
from typing import (
|
||||||
|
Any,
|
||||||
|
Generic,
|
||||||
|
TypeVar,
|
||||||
|
cast,
|
||||||
|
overload,
|
||||||
|
)
|
||||||
|
|
||||||
|
from ._core._eventloop import (
|
||||||
|
get_cancelled_exc_class,
|
||||||
|
threadlocals,
|
||||||
|
)
|
||||||
|
from ._core._eventloop import run as run_eventloop
|
||||||
|
from ._core._exceptions import NoEventLoopError
|
||||||
|
from ._core._synchronization import Event
|
||||||
|
from ._core._tasks import CancelScope, create_task_group
|
||||||
|
from .abc._tasks import TaskStatus
|
||||||
|
from .lowlevel import EventLoopToken, current_token
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import Self, TypeVarTuple, Unpack
|
||||||
|
else:
|
||||||
|
from typing_extensions import Self, TypeVarTuple, Unpack
|
||||||
|
|
||||||
|
T_Retval = TypeVar("T_Retval")
|
||||||
|
T_co = TypeVar("T_co", covariant=True)
|
||||||
|
PosArgsT = TypeVarTuple("PosArgsT")
|
||||||
|
|
||||||
|
|
||||||
|
def _token_or_error(token: EventLoopToken | None) -> EventLoopToken:
|
||||||
|
if token is not None:
|
||||||
|
return token
|
||||||
|
|
||||||
|
try:
|
||||||
|
return threadlocals.current_token
|
||||||
|
except AttributeError:
|
||||||
|
raise NoEventLoopError(
|
||||||
|
"Not running inside an AnyIO worker thread, and no event loop token was "
|
||||||
|
"provided"
|
||||||
|
) from None
|
||||||
|
|
||||||
|
|
||||||
|
def run(
|
||||||
|
func: Callable[[Unpack[PosArgsT]], Coroutine[Any, Any, T_co]],
|
||||||
|
*args: Unpack[PosArgsT],
|
||||||
|
token: EventLoopToken | None = None,
|
||||||
|
) -> T_co:
|
||||||
|
"""
|
||||||
|
Call a coroutine function from a worker thread.
|
||||||
|
|
||||||
|
:param func: a coroutine function
|
||||||
|
:param args: positional arguments for the callable
|
||||||
|
:param token: an event loop token to use to get back to the event loop thread
|
||||||
|
(required if calling this function from outside an AnyIO worker thread)
|
||||||
|
:return: the return value of the coroutine function
|
||||||
|
:raises MissingTokenError: if no token was provided and called from outside an
|
||||||
|
AnyIO worker thread
|
||||||
|
:raises RunFinishedError: if the event loop tied to ``token`` is no longer running
|
||||||
|
|
||||||
|
.. versionchanged:: 4.11.0
|
||||||
|
Added the ``token`` parameter.
|
||||||
|
|
||||||
|
"""
|
||||||
|
explicit_token = token is not None
|
||||||
|
token = _token_or_error(token)
|
||||||
|
return token.backend_class.run_async_from_thread(
|
||||||
|
func, args, token=token.native_token if explicit_token else None
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def run_sync(
|
||||||
|
func: Callable[[Unpack[PosArgsT]], T_Retval],
|
||||||
|
*args: Unpack[PosArgsT],
|
||||||
|
token: EventLoopToken | None = None,
|
||||||
|
) -> T_Retval:
|
||||||
|
"""
|
||||||
|
Call a function in the event loop thread from a worker thread.
|
||||||
|
|
||||||
|
:param func: a callable
|
||||||
|
:param args: positional arguments for the callable
|
||||||
|
:param token: an event loop token to use to get back to the event loop thread
|
||||||
|
(required if calling this function from outside an AnyIO worker thread)
|
||||||
|
:return: the return value of the callable
|
||||||
|
:raises MissingTokenError: if no token was provided and called from outside an
|
||||||
|
AnyIO worker thread
|
||||||
|
:raises RunFinishedError: if the event loop tied to ``token`` is no longer running
|
||||||
|
|
||||||
|
.. versionchanged:: 4.11.0
|
||||||
|
Added the ``token`` parameter.
|
||||||
|
|
||||||
|
"""
|
||||||
|
explicit_token = token is not None
|
||||||
|
token = _token_or_error(token)
|
||||||
|
return token.backend_class.run_sync_from_thread(
|
||||||
|
func, args, token=token.native_token if explicit_token else None
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class _BlockingAsyncContextManager(AbstractContextManager, Generic[T_co]):
|
||||||
|
_enter_future: Future[T_co]
|
||||||
|
_exit_future: Future[bool | None]
|
||||||
|
_exit_event: Event
|
||||||
|
_exit_exc_info: tuple[
|
||||||
|
type[BaseException] | None, BaseException | None, TracebackType | None
|
||||||
|
] = (None, None, None)
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self, async_cm: AbstractAsyncContextManager[T_co], portal: BlockingPortal
|
||||||
|
):
|
||||||
|
self._async_cm = async_cm
|
||||||
|
self._portal = portal
|
||||||
|
|
||||||
|
async def run_async_cm(self) -> bool | None:
|
||||||
|
try:
|
||||||
|
self._exit_event = Event()
|
||||||
|
value = await self._async_cm.__aenter__()
|
||||||
|
except BaseException as exc:
|
||||||
|
self._enter_future.set_exception(exc)
|
||||||
|
raise
|
||||||
|
else:
|
||||||
|
self._enter_future.set_result(value)
|
||||||
|
|
||||||
|
try:
|
||||||
|
# Wait for the sync context manager to exit.
|
||||||
|
# This next statement can raise `get_cancelled_exc_class()` if
|
||||||
|
# something went wrong in a task group in this async context
|
||||||
|
# manager.
|
||||||
|
await self._exit_event.wait()
|
||||||
|
finally:
|
||||||
|
# In case of cancellation, it could be that we end up here before
|
||||||
|
# `_BlockingAsyncContextManager.__exit__` is called, and an
|
||||||
|
# `_exit_exc_info` has been set.
|
||||||
|
result = await self._async_cm.__aexit__(*self._exit_exc_info)
|
||||||
|
|
||||||
|
return result
|
||||||
|
|
||||||
|
def __enter__(self) -> T_co:
|
||||||
|
self._enter_future = Future()
|
||||||
|
self._exit_future = self._portal.start_task_soon(self.run_async_cm)
|
||||||
|
return self._enter_future.result()
|
||||||
|
|
||||||
|
def __exit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_value: BaseException | None,
|
||||||
|
traceback: TracebackType | None,
|
||||||
|
/,
|
||||||
|
) -> bool | None:
|
||||||
|
self._exit_exc_info = exc_type, exc_value, traceback
|
||||||
|
self._portal.call(self._exit_event.set)
|
||||||
|
return self._exit_future.result()
|
||||||
|
|
||||||
|
|
||||||
|
class _BlockingPortalTaskStatus(TaskStatus):
|
||||||
|
def __init__(self, future: Future):
|
||||||
|
self._future = future
|
||||||
|
|
||||||
|
def started(self, value: object = None) -> None:
|
||||||
|
self._future.set_result(value)
|
||||||
|
|
||||||
|
|
||||||
|
class BlockingPortal:
|
||||||
|
"""
|
||||||
|
An object that lets external threads run code in an asynchronous event loop.
|
||||||
|
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self) -> None:
|
||||||
|
self._token = current_token()
|
||||||
|
self._event_loop_thread_id: int | None = get_ident()
|
||||||
|
self._stop_event = Event()
|
||||||
|
self._task_group = create_task_group()
|
||||||
|
|
||||||
|
async def __aenter__(self) -> Self:
|
||||||
|
await self._task_group.__aenter__()
|
||||||
|
return self
|
||||||
|
|
||||||
|
async def __aexit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> bool:
|
||||||
|
await self.stop()
|
||||||
|
return await self._task_group.__aexit__(exc_type, exc_val, exc_tb)
|
||||||
|
|
||||||
|
def _check_running(self) -> None:
|
||||||
|
if self._event_loop_thread_id is None:
|
||||||
|
raise RuntimeError("This portal is not running")
|
||||||
|
if self._event_loop_thread_id == get_ident():
|
||||||
|
raise RuntimeError(
|
||||||
|
"This method cannot be called from the event loop thread"
|
||||||
|
)
|
||||||
|
|
||||||
|
async def sleep_until_stopped(self) -> None:
|
||||||
|
"""Sleep until :meth:`stop` is called."""
|
||||||
|
await self._stop_event.wait()
|
||||||
|
|
||||||
|
async def stop(self, cancel_remaining: bool = False) -> None:
|
||||||
|
"""
|
||||||
|
Signal the portal to shut down.
|
||||||
|
|
||||||
|
This marks the portal as no longer accepting new calls and exits from
|
||||||
|
:meth:`sleep_until_stopped`.
|
||||||
|
|
||||||
|
:param cancel_remaining: ``True`` to cancel all the remaining tasks, ``False``
|
||||||
|
to let them finish before returning
|
||||||
|
|
||||||
|
"""
|
||||||
|
self._event_loop_thread_id = None
|
||||||
|
self._stop_event.set()
|
||||||
|
if cancel_remaining:
|
||||||
|
self._task_group.cancel_scope.cancel("the blocking portal is shutting down")
|
||||||
|
|
||||||
|
async def _call_func(
|
||||||
|
self,
|
||||||
|
func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval] | T_Retval],
|
||||||
|
args: tuple[Unpack[PosArgsT]],
|
||||||
|
kwargs: dict[str, Any],
|
||||||
|
future: Future[T_Retval],
|
||||||
|
) -> None:
|
||||||
|
event_loop_thread_id = self._event_loop_thread_id
|
||||||
|
|
||||||
|
def callback(f: Future[T_Retval]) -> None:
|
||||||
|
if f.cancelled():
|
||||||
|
if event_loop_thread_id == get_ident():
|
||||||
|
scope.cancel("the future was cancelled")
|
||||||
|
elif event_loop_thread_id is not None:
|
||||||
|
run_sync(
|
||||||
|
scope.cancel, "the future was cancelled", token=self._token
|
||||||
|
)
|
||||||
|
|
||||||
|
try:
|
||||||
|
retval_or_awaitable = func(*args, **kwargs)
|
||||||
|
if isawaitable(retval_or_awaitable):
|
||||||
|
with CancelScope() as scope:
|
||||||
|
future.add_done_callback(callback)
|
||||||
|
retval = await retval_or_awaitable
|
||||||
|
else:
|
||||||
|
retval = retval_or_awaitable
|
||||||
|
except get_cancelled_exc_class():
|
||||||
|
future.cancel()
|
||||||
|
future.set_running_or_notify_cancel()
|
||||||
|
except BaseException as exc:
|
||||||
|
if not future.cancelled():
|
||||||
|
future.set_exception(exc)
|
||||||
|
|
||||||
|
# Let base exceptions fall through
|
||||||
|
if not isinstance(exc, Exception):
|
||||||
|
raise
|
||||||
|
else:
|
||||||
|
if not future.cancelled():
|
||||||
|
future.set_result(retval)
|
||||||
|
finally:
|
||||||
|
scope = None # type: ignore[assignment]
|
||||||
|
|
||||||
|
def _spawn_task_from_thread(
|
||||||
|
self,
|
||||||
|
func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval] | T_Retval],
|
||||||
|
args: tuple[Unpack[PosArgsT]],
|
||||||
|
kwargs: dict[str, Any],
|
||||||
|
name: object,
|
||||||
|
future: Future[T_Retval],
|
||||||
|
) -> None:
|
||||||
|
"""
|
||||||
|
Spawn a new task using the given callable.
|
||||||
|
|
||||||
|
:param func: a callable
|
||||||
|
:param args: positional arguments to be passed to the callable
|
||||||
|
:param kwargs: keyword arguments to be passed to the callable
|
||||||
|
:param name: name of the task (will be coerced to a string if not ``None``)
|
||||||
|
:param future: a future that will resolve to the return value of the callable,
|
||||||
|
or the exception raised during its execution
|
||||||
|
|
||||||
|
"""
|
||||||
|
run_sync(
|
||||||
|
partial(self._task_group.start_soon, name=name),
|
||||||
|
self._call_func,
|
||||||
|
func,
|
||||||
|
args,
|
||||||
|
kwargs,
|
||||||
|
future,
|
||||||
|
token=self._token,
|
||||||
|
)
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def call(
|
||||||
|
self,
|
||||||
|
func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval]],
|
||||||
|
*args: Unpack[PosArgsT],
|
||||||
|
) -> T_Retval: ...
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def call(
|
||||||
|
self, func: Callable[[Unpack[PosArgsT]], T_Retval], *args: Unpack[PosArgsT]
|
||||||
|
) -> T_Retval: ...
|
||||||
|
|
||||||
|
def call(
|
||||||
|
self,
|
||||||
|
func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval] | T_Retval],
|
||||||
|
*args: Unpack[PosArgsT],
|
||||||
|
) -> T_Retval:
|
||||||
|
"""
|
||||||
|
Call the given function in the event loop thread.
|
||||||
|
|
||||||
|
If the callable returns a coroutine object, it is awaited on.
|
||||||
|
|
||||||
|
:param func: any callable
|
||||||
|
:raises RuntimeError: if the portal is not running or if this method is called
|
||||||
|
from within the event loop thread
|
||||||
|
|
||||||
|
"""
|
||||||
|
return cast(T_Retval, self.start_task_soon(func, *args).result())
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def start_task_soon(
|
||||||
|
self,
|
||||||
|
func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval]],
|
||||||
|
*args: Unpack[PosArgsT],
|
||||||
|
name: object = None,
|
||||||
|
) -> Future[T_Retval]: ...
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def start_task_soon(
|
||||||
|
self,
|
||||||
|
func: Callable[[Unpack[PosArgsT]], T_Retval],
|
||||||
|
*args: Unpack[PosArgsT],
|
||||||
|
name: object = None,
|
||||||
|
) -> Future[T_Retval]: ...
|
||||||
|
|
||||||
|
def start_task_soon(
|
||||||
|
self,
|
||||||
|
func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval] | T_Retval],
|
||||||
|
*args: Unpack[PosArgsT],
|
||||||
|
name: object = None,
|
||||||
|
) -> Future[T_Retval]:
|
||||||
|
"""
|
||||||
|
Start a task in the portal's task group.
|
||||||
|
|
||||||
|
The task will be run inside a cancel scope which can be cancelled by cancelling
|
||||||
|
the returned future.
|
||||||
|
|
||||||
|
:param func: the target function
|
||||||
|
:param args: positional arguments passed to ``func``
|
||||||
|
:param name: name of the task (will be coerced to a string if not ``None``)
|
||||||
|
:return: a future that resolves with the return value of the callable if the
|
||||||
|
task completes successfully, or with the exception raised in the task
|
||||||
|
:raises RuntimeError: if the portal is not running or if this method is called
|
||||||
|
from within the event loop thread
|
||||||
|
:rtype: concurrent.futures.Future[T_Retval]
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
self._check_running()
|
||||||
|
f: Future[T_Retval] = Future()
|
||||||
|
self._spawn_task_from_thread(func, args, {}, name, f)
|
||||||
|
return f
|
||||||
|
|
||||||
|
def start_task(
|
||||||
|
self,
|
||||||
|
func: Callable[..., Awaitable[T_Retval]],
|
||||||
|
*args: object,
|
||||||
|
name: object = None,
|
||||||
|
) -> tuple[Future[T_Retval], Any]:
|
||||||
|
"""
|
||||||
|
Start a task in the portal's task group and wait until it signals for readiness.
|
||||||
|
|
||||||
|
This method works the same way as :meth:`.abc.TaskGroup.start`.
|
||||||
|
|
||||||
|
:param func: the target function
|
||||||
|
:param args: positional arguments passed to ``func``
|
||||||
|
:param name: name of the task (will be coerced to a string if not ``None``)
|
||||||
|
:return: a tuple of (future, task_status_value) where the ``task_status_value``
|
||||||
|
is the value passed to ``task_status.started()`` from within the target
|
||||||
|
function
|
||||||
|
:rtype: tuple[concurrent.futures.Future[T_Retval], Any]
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
def task_done(future: Future[T_Retval]) -> None:
|
||||||
|
if not task_status_future.done():
|
||||||
|
if future.cancelled():
|
||||||
|
task_status_future.cancel()
|
||||||
|
elif future.exception():
|
||||||
|
task_status_future.set_exception(future.exception())
|
||||||
|
else:
|
||||||
|
exc = RuntimeError(
|
||||||
|
"Task exited without calling task_status.started()"
|
||||||
|
)
|
||||||
|
task_status_future.set_exception(exc)
|
||||||
|
|
||||||
|
self._check_running()
|
||||||
|
task_status_future: Future = Future()
|
||||||
|
task_status = _BlockingPortalTaskStatus(task_status_future)
|
||||||
|
f: Future = Future()
|
||||||
|
f.add_done_callback(task_done)
|
||||||
|
self._spawn_task_from_thread(func, args, {"task_status": task_status}, name, f)
|
||||||
|
return f, task_status_future.result()
|
||||||
|
|
||||||
|
def wrap_async_context_manager(
|
||||||
|
self, cm: AbstractAsyncContextManager[T_co]
|
||||||
|
) -> AbstractContextManager[T_co]:
|
||||||
|
"""
|
||||||
|
Wrap an async context manager as a synchronous context manager via this portal.
|
||||||
|
|
||||||
|
Spawns a task that will call both ``__aenter__()`` and ``__aexit__()``, stopping
|
||||||
|
in the middle until the synchronous context manager exits.
|
||||||
|
|
||||||
|
:param cm: an asynchronous context manager
|
||||||
|
:return: a synchronous context manager
|
||||||
|
|
||||||
|
.. versionadded:: 2.1
|
||||||
|
|
||||||
|
"""
|
||||||
|
return _BlockingAsyncContextManager(cm, self)
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class BlockingPortalProvider:
|
||||||
|
"""
|
||||||
|
A manager for a blocking portal. Used as a context manager. The first thread to
|
||||||
|
enter this context manager causes a blocking portal to be started with the specific
|
||||||
|
parameters, and the last thread to exit causes the portal to be shut down. Thus,
|
||||||
|
there will be exactly one blocking portal running in this context as long as at
|
||||||
|
least one thread has entered this context manager.
|
||||||
|
|
||||||
|
The parameters are the same as for :func:`~anyio.run`.
|
||||||
|
|
||||||
|
:param backend: name of the backend
|
||||||
|
:param backend_options: backend options
|
||||||
|
|
||||||
|
.. versionadded:: 4.4
|
||||||
|
"""
|
||||||
|
|
||||||
|
backend: str = "asyncio"
|
||||||
|
backend_options: dict[str, Any] | None = None
|
||||||
|
_lock: Lock = field(init=False, default_factory=Lock)
|
||||||
|
_leases: int = field(init=False, default=0)
|
||||||
|
_portal: BlockingPortal = field(init=False)
|
||||||
|
_portal_cm: AbstractContextManager[BlockingPortal] | None = field(
|
||||||
|
init=False, default=None
|
||||||
|
)
|
||||||
|
|
||||||
|
def __enter__(self) -> BlockingPortal:
|
||||||
|
with self._lock:
|
||||||
|
if self._portal_cm is None:
|
||||||
|
self._portal_cm = start_blocking_portal(
|
||||||
|
self.backend, self.backend_options
|
||||||
|
)
|
||||||
|
self._portal = self._portal_cm.__enter__()
|
||||||
|
|
||||||
|
self._leases += 1
|
||||||
|
return self._portal
|
||||||
|
|
||||||
|
def __exit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
portal_cm: AbstractContextManager[BlockingPortal] | None = None
|
||||||
|
with self._lock:
|
||||||
|
assert self._portal_cm
|
||||||
|
assert self._leases > 0
|
||||||
|
self._leases -= 1
|
||||||
|
if not self._leases:
|
||||||
|
portal_cm = self._portal_cm
|
||||||
|
self._portal_cm = None
|
||||||
|
del self._portal
|
||||||
|
|
||||||
|
if portal_cm:
|
||||||
|
portal_cm.__exit__(None, None, None)
|
||||||
|
|
||||||
|
|
||||||
|
@contextmanager
|
||||||
|
def start_blocking_portal(
|
||||||
|
backend: str = "asyncio",
|
||||||
|
backend_options: dict[str, Any] | None = None,
|
||||||
|
*,
|
||||||
|
name: str | None = None,
|
||||||
|
) -> Generator[BlockingPortal, Any, None]:
|
||||||
|
"""
|
||||||
|
Start a new event loop in a new thread and run a blocking portal in its main task.
|
||||||
|
|
||||||
|
The parameters are the same as for :func:`~anyio.run`.
|
||||||
|
|
||||||
|
:param backend: name of the backend
|
||||||
|
:param backend_options: backend options
|
||||||
|
:param name: name of the thread
|
||||||
|
:return: a context manager that yields a blocking portal
|
||||||
|
|
||||||
|
.. versionchanged:: 3.0
|
||||||
|
Usage as a context manager is now required.
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
async def run_portal() -> None:
|
||||||
|
async with BlockingPortal() as portal_:
|
||||||
|
if name is None:
|
||||||
|
current_thread().name = f"{backend}-portal-{id(portal_):x}"
|
||||||
|
|
||||||
|
future.set_result(portal_)
|
||||||
|
await portal_.sleep_until_stopped()
|
||||||
|
|
||||||
|
def run_blocking_portal() -> None:
|
||||||
|
if future.set_running_or_notify_cancel():
|
||||||
|
try:
|
||||||
|
run_eventloop(
|
||||||
|
run_portal, backend=backend, backend_options=backend_options
|
||||||
|
)
|
||||||
|
except BaseException as exc:
|
||||||
|
if not future.done():
|
||||||
|
future.set_exception(exc)
|
||||||
|
|
||||||
|
future: Future[BlockingPortal] = Future()
|
||||||
|
kwargs: dict[str, Any] = {}
|
||||||
|
if sys.version_info >= (3, 14):
|
||||||
|
kwargs["context"] = Context()
|
||||||
|
|
||||||
|
thread = Thread(target=run_blocking_portal, daemon=True, name=name, **kwargs)
|
||||||
|
thread.start()
|
||||||
|
try:
|
||||||
|
cancel_remaining_tasks = False
|
||||||
|
portal = future.result()
|
||||||
|
try:
|
||||||
|
yield portal
|
||||||
|
except BaseException:
|
||||||
|
cancel_remaining_tasks = True
|
||||||
|
raise
|
||||||
|
finally:
|
||||||
|
try:
|
||||||
|
portal.call(portal.stop, cancel_remaining_tasks)
|
||||||
|
except RuntimeError:
|
||||||
|
pass
|
||||||
|
finally:
|
||||||
|
thread.join()
|
||||||
|
|
||||||
|
|
||||||
|
def check_cancelled() -> None:
|
||||||
|
"""
|
||||||
|
Check if the cancel scope of the host task's running the current worker thread has
|
||||||
|
been cancelled.
|
||||||
|
|
||||||
|
If the host task's current cancel scope has indeed been cancelled, the
|
||||||
|
backend-specific cancellation exception will be raised.
|
||||||
|
|
||||||
|
:raises RuntimeError: if the current thread was not spawned by
|
||||||
|
:func:`.to_thread.run_sync`
|
||||||
|
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
token: EventLoopToken = threadlocals.current_token
|
||||||
|
except AttributeError:
|
||||||
|
raise NoEventLoopError(
|
||||||
|
"This function can only be called inside an AnyIO worker thread"
|
||||||
|
) from None
|
||||||
|
|
||||||
|
token.backend_class.check_cancelled()
|
||||||
@@ -0,0 +1,400 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"AsyncCacheInfo",
|
||||||
|
"AsyncCacheParameters",
|
||||||
|
"AsyncLRUCacheWrapper",
|
||||||
|
"cache",
|
||||||
|
"lru_cache",
|
||||||
|
"reduce",
|
||||||
|
)
|
||||||
|
|
||||||
|
import functools
|
||||||
|
from collections import OrderedDict
|
||||||
|
from collections.abc import (
|
||||||
|
AsyncIterable,
|
||||||
|
Awaitable,
|
||||||
|
Callable,
|
||||||
|
Coroutine,
|
||||||
|
Hashable,
|
||||||
|
Iterable,
|
||||||
|
)
|
||||||
|
from functools import update_wrapper
|
||||||
|
from inspect import iscoroutinefunction
|
||||||
|
from typing import (
|
||||||
|
Any,
|
||||||
|
Generic,
|
||||||
|
NamedTuple,
|
||||||
|
ParamSpec,
|
||||||
|
TypedDict,
|
||||||
|
TypeVar,
|
||||||
|
cast,
|
||||||
|
final,
|
||||||
|
overload,
|
||||||
|
)
|
||||||
|
from weakref import WeakKeyDictionary
|
||||||
|
|
||||||
|
from ._core._eventloop import current_time
|
||||||
|
from ._core._synchronization import Lock
|
||||||
|
from .lowlevel import RunVar, checkpoint
|
||||||
|
|
||||||
|
T = TypeVar("T")
|
||||||
|
S = TypeVar("S")
|
||||||
|
P = ParamSpec("P")
|
||||||
|
lru_cache_items: RunVar[
|
||||||
|
WeakKeyDictionary[
|
||||||
|
AsyncLRUCacheWrapper[Any, Any],
|
||||||
|
OrderedDict[
|
||||||
|
Hashable,
|
||||||
|
tuple[_InitialMissingType, Lock, float | None]
|
||||||
|
| tuple[Any, None, float | None],
|
||||||
|
],
|
||||||
|
]
|
||||||
|
] = RunVar("lru_cache_items")
|
||||||
|
|
||||||
|
|
||||||
|
class _InitialMissingType:
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
initial_missing: _InitialMissingType = _InitialMissingType()
|
||||||
|
|
||||||
|
|
||||||
|
class AsyncCacheInfo(NamedTuple):
|
||||||
|
hits: int
|
||||||
|
misses: int
|
||||||
|
maxsize: int | None
|
||||||
|
currsize: int
|
||||||
|
ttl: int | None
|
||||||
|
|
||||||
|
|
||||||
|
class AsyncCacheParameters(TypedDict):
|
||||||
|
maxsize: int | None
|
||||||
|
typed: bool
|
||||||
|
always_checkpoint: bool
|
||||||
|
ttl: int | None
|
||||||
|
|
||||||
|
|
||||||
|
class _LRUMethodWrapper(Generic[T]):
|
||||||
|
def __init__(self, wrapper: AsyncLRUCacheWrapper[..., T], instance: object):
|
||||||
|
self.__wrapper = wrapper
|
||||||
|
self.__instance = instance
|
||||||
|
|
||||||
|
def cache_info(self) -> AsyncCacheInfo:
|
||||||
|
return self.__wrapper.cache_info()
|
||||||
|
|
||||||
|
def cache_parameters(self) -> AsyncCacheParameters:
|
||||||
|
return self.__wrapper.cache_parameters()
|
||||||
|
|
||||||
|
def cache_clear(self) -> None:
|
||||||
|
self.__wrapper.cache_clear()
|
||||||
|
|
||||||
|
async def __call__(self, *args: Any, **kwargs: Any) -> T:
|
||||||
|
if self.__instance is None:
|
||||||
|
return await self.__wrapper(*args, **kwargs)
|
||||||
|
|
||||||
|
return await self.__wrapper(self.__instance, *args, **kwargs)
|
||||||
|
|
||||||
|
|
||||||
|
@final
|
||||||
|
class AsyncLRUCacheWrapper(Generic[P, T]):
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
func: Callable[P, Awaitable[T]],
|
||||||
|
maxsize: int | None,
|
||||||
|
typed: bool,
|
||||||
|
always_checkpoint: bool,
|
||||||
|
ttl: int | None,
|
||||||
|
):
|
||||||
|
self.__wrapped__ = func
|
||||||
|
self._hits: int = 0
|
||||||
|
self._misses: int = 0
|
||||||
|
self._maxsize = max(maxsize, 0) if maxsize is not None else None
|
||||||
|
self._currsize: int = 0
|
||||||
|
self._typed = typed
|
||||||
|
self._always_checkpoint = always_checkpoint
|
||||||
|
self._ttl = ttl
|
||||||
|
update_wrapper(self, func)
|
||||||
|
|
||||||
|
def cache_info(self) -> AsyncCacheInfo:
|
||||||
|
return AsyncCacheInfo(
|
||||||
|
self._hits, self._misses, self._maxsize, self._currsize, self._ttl
|
||||||
|
)
|
||||||
|
|
||||||
|
def cache_parameters(self) -> AsyncCacheParameters:
|
||||||
|
return {
|
||||||
|
"maxsize": self._maxsize,
|
||||||
|
"typed": self._typed,
|
||||||
|
"always_checkpoint": self._always_checkpoint,
|
||||||
|
"ttl": self._ttl,
|
||||||
|
}
|
||||||
|
|
||||||
|
def cache_clear(self) -> None:
|
||||||
|
if cache := lru_cache_items.get(None):
|
||||||
|
cache.pop(self, None)
|
||||||
|
self._hits = self._misses = self._currsize = 0
|
||||||
|
|
||||||
|
async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:
|
||||||
|
# Easy case first: if maxsize == 0, no caching is done
|
||||||
|
if self._maxsize == 0:
|
||||||
|
value = await self.__wrapped__(*args, **kwargs)
|
||||||
|
self._misses += 1
|
||||||
|
return value
|
||||||
|
|
||||||
|
# The key is constructed as a flat tuple to avoid memory overhead
|
||||||
|
key: tuple[Any, ...] = args
|
||||||
|
if kwargs:
|
||||||
|
# initial_missing is used as a separator
|
||||||
|
key += (initial_missing,) + sum(kwargs.items(), ())
|
||||||
|
|
||||||
|
if self._typed:
|
||||||
|
key += tuple(type(arg) for arg in args)
|
||||||
|
if kwargs:
|
||||||
|
key += (initial_missing,) + tuple(type(val) for val in kwargs.values())
|
||||||
|
|
||||||
|
try:
|
||||||
|
cache = lru_cache_items.get()
|
||||||
|
except LookupError:
|
||||||
|
cache = WeakKeyDictionary()
|
||||||
|
lru_cache_items.set(cache)
|
||||||
|
|
||||||
|
try:
|
||||||
|
cache_entry = cache[self]
|
||||||
|
except KeyError:
|
||||||
|
cache_entry = cache[self] = OrderedDict()
|
||||||
|
|
||||||
|
cached_value: T | _InitialMissingType
|
||||||
|
try:
|
||||||
|
cached_value, lock, expires_at = cache_entry[key]
|
||||||
|
except KeyError:
|
||||||
|
# We're the first task to call this function
|
||||||
|
cached_value, lock, expires_at = (
|
||||||
|
initial_missing,
|
||||||
|
Lock(fast_acquire=not self._always_checkpoint),
|
||||||
|
None,
|
||||||
|
)
|
||||||
|
cache_entry[key] = cached_value, lock, expires_at
|
||||||
|
|
||||||
|
if lock is None:
|
||||||
|
if expires_at is not None and current_time() >= expires_at:
|
||||||
|
self._currsize -= 1
|
||||||
|
cached_value, lock, expires_at = (
|
||||||
|
initial_missing,
|
||||||
|
Lock(fast_acquire=not self._always_checkpoint),
|
||||||
|
None,
|
||||||
|
)
|
||||||
|
cache_entry[key] = cached_value, lock, expires_at
|
||||||
|
else:
|
||||||
|
# The value was already cached
|
||||||
|
self._hits += 1
|
||||||
|
cache_entry.move_to_end(key)
|
||||||
|
if self._always_checkpoint:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
return cast(T, cached_value)
|
||||||
|
|
||||||
|
async with lock:
|
||||||
|
# Check if another task filled the cache while we acquired the lock
|
||||||
|
if (cached_value := cache_entry[key][0]) is initial_missing:
|
||||||
|
self._misses += 1
|
||||||
|
if self._maxsize is not None and self._currsize >= self._maxsize:
|
||||||
|
cache_entry.popitem(last=False)
|
||||||
|
else:
|
||||||
|
self._currsize += 1
|
||||||
|
|
||||||
|
value = await self.__wrapped__(*args, **kwargs)
|
||||||
|
expires_at = (
|
||||||
|
current_time() + self._ttl if self._ttl is not None else None
|
||||||
|
)
|
||||||
|
cache_entry[key] = value, None, expires_at
|
||||||
|
else:
|
||||||
|
# Another task filled the cache while we were waiting for the lock
|
||||||
|
self._hits += 1
|
||||||
|
cache_entry.move_to_end(key)
|
||||||
|
value = cast(T, cached_value)
|
||||||
|
|
||||||
|
return value
|
||||||
|
|
||||||
|
def __get__(
|
||||||
|
self, instance: object, owner: type | None = None
|
||||||
|
) -> _LRUMethodWrapper[T]:
|
||||||
|
wrapper = _LRUMethodWrapper(self, instance)
|
||||||
|
update_wrapper(wrapper, self.__wrapped__)
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
|
||||||
|
class _LRUCacheWrapper:
|
||||||
|
def __init__(
|
||||||
|
self, maxsize: int | None, typed: bool, always_checkpoint: bool, ttl: int | None
|
||||||
|
):
|
||||||
|
self._maxsize = maxsize
|
||||||
|
self._typed = typed
|
||||||
|
self._always_checkpoint = always_checkpoint
|
||||||
|
self._ttl = ttl
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def __call__( # type: ignore[overload-overlap]
|
||||||
|
self, func: Callable[P, Coroutine[Any, Any, T]], /
|
||||||
|
) -> AsyncLRUCacheWrapper[P, T]: ...
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def __call__(
|
||||||
|
self, func: Callable[..., T], /
|
||||||
|
) -> functools._lru_cache_wrapper[T]: ...
|
||||||
|
|
||||||
|
def __call__(
|
||||||
|
self, f: Callable[P, Coroutine[Any, Any, T]] | Callable[..., T], /
|
||||||
|
) -> AsyncLRUCacheWrapper[P, T] | functools._lru_cache_wrapper[T]:
|
||||||
|
if iscoroutinefunction(f):
|
||||||
|
return AsyncLRUCacheWrapper(
|
||||||
|
f, self._maxsize, self._typed, self._always_checkpoint, self._ttl
|
||||||
|
)
|
||||||
|
|
||||||
|
return functools.lru_cache(maxsize=self._maxsize, typed=self._typed)(f) # type: ignore[arg-type]
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def cache( # type: ignore[overload-overlap]
|
||||||
|
func: Callable[P, Coroutine[Any, Any, T]], /
|
||||||
|
) -> AsyncLRUCacheWrapper[P, T]: ...
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def cache(func: Callable[..., T], /) -> functools._lru_cache_wrapper[T]: ...
|
||||||
|
|
||||||
|
|
||||||
|
def cache(func: Callable[..., Any] | Callable[P, Coroutine[Any, Any, Any]], /) -> Any:
|
||||||
|
"""
|
||||||
|
A convenient shortcut for :func:`lru_cache` with ``maxsize=None``.
|
||||||
|
|
||||||
|
This is the asynchronous equivalent to :func:`functools.cache`.
|
||||||
|
|
||||||
|
"""
|
||||||
|
return lru_cache(maxsize=None)(func)
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def lru_cache(
|
||||||
|
*,
|
||||||
|
maxsize: int | None = ...,
|
||||||
|
typed: bool = ...,
|
||||||
|
always_checkpoint: bool = ...,
|
||||||
|
ttl: int | None = ...,
|
||||||
|
) -> _LRUCacheWrapper: ...
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def lru_cache( # type: ignore[overload-overlap]
|
||||||
|
func: Callable[P, Coroutine[Any, Any, T]], /
|
||||||
|
) -> AsyncLRUCacheWrapper[P, T]: ...
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def lru_cache(func: Callable[..., T], /) -> functools._lru_cache_wrapper[T]: ...
|
||||||
|
|
||||||
|
|
||||||
|
def lru_cache(
|
||||||
|
func: Callable[..., Coroutine[Any, Any, Any]] | Callable[..., Any] | None = None,
|
||||||
|
/,
|
||||||
|
*,
|
||||||
|
maxsize: int | None = 128,
|
||||||
|
typed: bool = False,
|
||||||
|
always_checkpoint: bool = False,
|
||||||
|
ttl: int | None = None,
|
||||||
|
) -> Any:
|
||||||
|
"""
|
||||||
|
An asynchronous version of :func:`functools.lru_cache`.
|
||||||
|
|
||||||
|
If a synchronous function is passed, the standard library
|
||||||
|
:func:`functools.lru_cache` is applied instead.
|
||||||
|
|
||||||
|
:param always_checkpoint: if ``True``, every call to the cached function will be
|
||||||
|
guaranteed to yield control to the event loop at least once
|
||||||
|
:param ttl: time in seconds after which to invalidate cache entries
|
||||||
|
|
||||||
|
.. note:: Caches and locks are managed on a per-event loop basis.
|
||||||
|
|
||||||
|
"""
|
||||||
|
if func is None:
|
||||||
|
return _LRUCacheWrapper(maxsize, typed, always_checkpoint, ttl)
|
||||||
|
|
||||||
|
if not callable(func):
|
||||||
|
raise TypeError("the first argument must be callable")
|
||||||
|
|
||||||
|
return _LRUCacheWrapper(maxsize, typed, always_checkpoint, ttl)(func)
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def reduce(
|
||||||
|
function: Callable[[T, S], Awaitable[T]],
|
||||||
|
iterable: Iterable[S] | AsyncIterable[S],
|
||||||
|
/,
|
||||||
|
initial: T,
|
||||||
|
) -> T: ...
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
async def reduce(
|
||||||
|
function: Callable[[T, T], Awaitable[T]],
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
/,
|
||||||
|
) -> T: ...
|
||||||
|
|
||||||
|
|
||||||
|
async def reduce( # type: ignore[misc]
|
||||||
|
function: Callable[[T, T], Awaitable[T]] | Callable[[T, S], Awaitable[T]],
|
||||||
|
iterable: Iterable[T] | Iterable[S] | AsyncIterable[T] | AsyncIterable[S],
|
||||||
|
/,
|
||||||
|
initial: T | _InitialMissingType = initial_missing,
|
||||||
|
) -> T:
|
||||||
|
"""
|
||||||
|
Asynchronous version of :func:`functools.reduce`.
|
||||||
|
|
||||||
|
:param function: a coroutine function that takes two arguments: the accumulated
|
||||||
|
value and the next element from the iterable
|
||||||
|
:param iterable: an iterable or async iterable
|
||||||
|
:param initial: the initial value (if missing, the first element of the iterable is
|
||||||
|
used as the initial value)
|
||||||
|
|
||||||
|
"""
|
||||||
|
element: Any
|
||||||
|
function_called = False
|
||||||
|
if isinstance(iterable, AsyncIterable):
|
||||||
|
async_it = iterable.__aiter__()
|
||||||
|
if initial is initial_missing:
|
||||||
|
try:
|
||||||
|
value = cast(T, await async_it.__anext__())
|
||||||
|
except StopAsyncIteration:
|
||||||
|
raise TypeError(
|
||||||
|
"reduce() of empty sequence with no initial value"
|
||||||
|
) from None
|
||||||
|
else:
|
||||||
|
value = cast(T, initial)
|
||||||
|
|
||||||
|
async for element in async_it:
|
||||||
|
value = await function(value, element)
|
||||||
|
function_called = True
|
||||||
|
elif isinstance(iterable, Iterable):
|
||||||
|
it = iter(iterable)
|
||||||
|
if initial is initial_missing:
|
||||||
|
try:
|
||||||
|
value = cast(T, next(it))
|
||||||
|
except StopIteration:
|
||||||
|
raise TypeError(
|
||||||
|
"reduce() of empty sequence with no initial value"
|
||||||
|
) from None
|
||||||
|
else:
|
||||||
|
value = cast(T, initial)
|
||||||
|
|
||||||
|
for element in it:
|
||||||
|
value = await function(value, element)
|
||||||
|
function_called = True
|
||||||
|
else:
|
||||||
|
raise TypeError("reduce() argument 2 must be an iterable or async iterable")
|
||||||
|
|
||||||
|
# Make sure there is at least one checkpoint, even if an empty iterable and an
|
||||||
|
# initial value were given
|
||||||
|
if not function_called:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
return value
|
||||||
@@ -0,0 +1,629 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"Chain",
|
||||||
|
"accumulate",
|
||||||
|
"batched",
|
||||||
|
"combinations",
|
||||||
|
"combinations_with_replacement",
|
||||||
|
"compress",
|
||||||
|
"count",
|
||||||
|
"cycle",
|
||||||
|
"dropwhile",
|
||||||
|
"filterfalse",
|
||||||
|
"groupby",
|
||||||
|
"islice",
|
||||||
|
"pairwise",
|
||||||
|
"permutations",
|
||||||
|
"product",
|
||||||
|
"repeat",
|
||||||
|
"starmap",
|
||||||
|
"takewhile",
|
||||||
|
"tee",
|
||||||
|
"zip_longest",
|
||||||
|
)
|
||||||
|
|
||||||
|
import itertools
|
||||||
|
import operator
|
||||||
|
import sys
|
||||||
|
from collections.abc import (
|
||||||
|
AsyncGenerator,
|
||||||
|
AsyncIterable,
|
||||||
|
AsyncIterator,
|
||||||
|
Awaitable,
|
||||||
|
Callable,
|
||||||
|
Iterable,
|
||||||
|
Iterator,
|
||||||
|
)
|
||||||
|
from dataclasses import dataclass, field
|
||||||
|
from typing import Any, Generic, TypeVar, cast, overload
|
||||||
|
|
||||||
|
from ._core._synchronization import Lock
|
||||||
|
from ._core._tasks import CancelScope
|
||||||
|
from .lowlevel import cancel_shielded_checkpoint, checkpoint, checkpoint_if_cancelled
|
||||||
|
|
||||||
|
if sys.version_info < (3, 15):
|
||||||
|
from typing_extensions import sentinel
|
||||||
|
|
||||||
|
T = TypeVar("T")
|
||||||
|
R = TypeVar("R")
|
||||||
|
_tee_end = sentinel("_tee_end")
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class _IterableAsyncIterator(AsyncIterator[T]):
|
||||||
|
iterator: Iterator[T]
|
||||||
|
|
||||||
|
async def __anext__(self) -> T:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
try:
|
||||||
|
result = next(self.iterator)
|
||||||
|
except StopIteration:
|
||||||
|
await cancel_shielded_checkpoint()
|
||||||
|
raise StopAsyncIteration from None
|
||||||
|
|
||||||
|
await cancel_shielded_checkpoint()
|
||||||
|
return result
|
||||||
|
|
||||||
|
|
||||||
|
def _iterate(iterable: Iterable[T] | AsyncIterable[T]) -> AsyncIterator[T]:
|
||||||
|
if isinstance(iterable, AsyncIterator):
|
||||||
|
return iterable
|
||||||
|
|
||||||
|
if isinstance(iterable, AsyncIterable):
|
||||||
|
return iterable.__aiter__()
|
||||||
|
|
||||||
|
return _IterableAsyncIterator(iter(iterable))
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class _TeeLink(Generic[T]):
|
||||||
|
value: object | None = None
|
||||||
|
next: _TeeLink[T] | None = None
|
||||||
|
filled: bool = False
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class _TeeState(Generic[T]):
|
||||||
|
iterator: AsyncIterator[T]
|
||||||
|
lock: Lock = field(default_factory=Lock)
|
||||||
|
|
||||||
|
async def fill(self, link: _TeeLink[T]) -> bool:
|
||||||
|
if link.filled:
|
||||||
|
return False
|
||||||
|
|
||||||
|
async with self.lock:
|
||||||
|
if link.filled:
|
||||||
|
return True
|
||||||
|
|
||||||
|
link.value = await anext(self.iterator, _tee_end)
|
||||||
|
if link.value is not _tee_end:
|
||||||
|
link.next = _TeeLink()
|
||||||
|
|
||||||
|
link.filled = True
|
||||||
|
return True
|
||||||
|
|
||||||
|
|
||||||
|
class _TeeAsyncIterator(AsyncIterator[T]):
|
||||||
|
_state: _TeeState[T]
|
||||||
|
_link: _TeeLink[T]
|
||||||
|
_element_yielded: bool
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self, iterable: Iterable[T] | AsyncIterable[T] | _TeeAsyncIterator[T]
|
||||||
|
) -> None:
|
||||||
|
if isinstance(iterable, _TeeAsyncIterator):
|
||||||
|
self._state = iterable._state
|
||||||
|
self._link = iterable._link
|
||||||
|
else:
|
||||||
|
self._state = _TeeState(_iterate(iterable))
|
||||||
|
self._link = _TeeLink()
|
||||||
|
|
||||||
|
self._element_yielded = False
|
||||||
|
|
||||||
|
async def __anext__(self) -> T:
|
||||||
|
had_yieldpoint = await self._state.fill(self._link)
|
||||||
|
if self._link.value is _tee_end:
|
||||||
|
if not self._element_yielded:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
raise StopAsyncIteration
|
||||||
|
|
||||||
|
if not had_yieldpoint:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
|
||||||
|
self._element_yielded = True
|
||||||
|
value = cast(T, self._link.value)
|
||||||
|
next_link = self._link.next
|
||||||
|
assert next_link is not None
|
||||||
|
self._link = next_link
|
||||||
|
if not had_yieldpoint:
|
||||||
|
await cancel_shielded_checkpoint()
|
||||||
|
|
||||||
|
return value
|
||||||
|
|
||||||
|
|
||||||
|
async def _operator_add(x: T, y: T) -> T:
|
||||||
|
return operator.add(x, y)
|
||||||
|
|
||||||
|
|
||||||
|
async def accumulate(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
function: Callable[[T, T], Awaitable[T]] = _operator_add,
|
||||||
|
*,
|
||||||
|
initial: T | None = None,
|
||||||
|
) -> AsyncGenerator[T, None]:
|
||||||
|
iterator = _iterate(iterable)
|
||||||
|
if initial is None:
|
||||||
|
try:
|
||||||
|
total = await anext(iterator)
|
||||||
|
except StopAsyncIteration:
|
||||||
|
await checkpoint()
|
||||||
|
return
|
||||||
|
else:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
total = initial
|
||||||
|
await cancel_shielded_checkpoint()
|
||||||
|
|
||||||
|
yield total
|
||||||
|
|
||||||
|
async for element in iterator:
|
||||||
|
total = await function(total, element)
|
||||||
|
yield total
|
||||||
|
|
||||||
|
|
||||||
|
async def batched(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T], n: int, *, strict: bool = False
|
||||||
|
) -> AsyncGenerator[tuple[T, ...], None]:
|
||||||
|
if n < 1:
|
||||||
|
raise ValueError("n must be at least one")
|
||||||
|
|
||||||
|
iterator = _iterate(iterable)
|
||||||
|
|
||||||
|
while True:
|
||||||
|
batch: list[T] = []
|
||||||
|
for _ in range(n):
|
||||||
|
try:
|
||||||
|
batch.append(await anext(iterator))
|
||||||
|
except StopAsyncIteration:
|
||||||
|
if not batch:
|
||||||
|
await checkpoint()
|
||||||
|
return
|
||||||
|
if strict:
|
||||||
|
raise ValueError("batched(): incomplete batch") from None
|
||||||
|
|
||||||
|
yield tuple(batch)
|
||||||
|
return
|
||||||
|
|
||||||
|
yield tuple(batch)
|
||||||
|
|
||||||
|
|
||||||
|
class Chain:
|
||||||
|
def __call__(
|
||||||
|
self, *iterables: Iterable[T] | AsyncIterable[T]
|
||||||
|
) -> AsyncGenerator[T, None]:
|
||||||
|
return self.from_iterable(iterables)
|
||||||
|
|
||||||
|
async def from_iterable(
|
||||||
|
self,
|
||||||
|
iterables: (
|
||||||
|
Iterable[Iterable[T] | AsyncIterable[T]]
|
||||||
|
| AsyncIterable[Iterable[T] | AsyncIterable[T]]
|
||||||
|
),
|
||||||
|
) -> AsyncGenerator[T, None]:
|
||||||
|
element_yielded = False
|
||||||
|
outer_iter = _iterate(iterables)
|
||||||
|
|
||||||
|
try:
|
||||||
|
async for iterable in outer_iter:
|
||||||
|
async for element in _iterate(iterable):
|
||||||
|
element_yielded = True
|
||||||
|
yield element
|
||||||
|
finally:
|
||||||
|
aclose = getattr(outer_iter, "aclose", None)
|
||||||
|
if aclose is not None:
|
||||||
|
with CancelScope(shield=True):
|
||||||
|
await aclose()
|
||||||
|
|
||||||
|
if not element_yielded:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
|
||||||
|
chain: Chain = Chain()
|
||||||
|
|
||||||
|
|
||||||
|
async def combinations(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T], r: int
|
||||||
|
) -> AsyncGenerator[tuple[T, ...], None]:
|
||||||
|
pool: list[T] = [element async for element in _iterate(iterable)]
|
||||||
|
async for combination in _iterate(itertools.combinations(pool, r)):
|
||||||
|
yield combination
|
||||||
|
|
||||||
|
|
||||||
|
async def combinations_with_replacement(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T], r: int
|
||||||
|
) -> AsyncGenerator[tuple[T, ...], None]:
|
||||||
|
pool: list[T] = [element async for element in _iterate(iterable)]
|
||||||
|
async for combination in _iterate(itertools.combinations_with_replacement(pool, r)):
|
||||||
|
yield combination
|
||||||
|
|
||||||
|
|
||||||
|
async def compress(
|
||||||
|
data: Iterable[T] | AsyncIterable[T],
|
||||||
|
selectors: Iterable[object] | AsyncIterable[object],
|
||||||
|
) -> AsyncGenerator[T, None]:
|
||||||
|
data_iterator = _iterate(data)
|
||||||
|
selector_iterator = _iterate(selectors)
|
||||||
|
element_yielded = False
|
||||||
|
|
||||||
|
while True:
|
||||||
|
try:
|
||||||
|
datum = await anext(data_iterator)
|
||||||
|
selector = await anext(selector_iterator)
|
||||||
|
except StopAsyncIteration:
|
||||||
|
if not element_yielded:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
return
|
||||||
|
|
||||||
|
if selector:
|
||||||
|
element_yielded = True
|
||||||
|
yield datum
|
||||||
|
|
||||||
|
|
||||||
|
async def count(start: int = 0, step: int = 1) -> AsyncGenerator[int, None]:
|
||||||
|
n = start
|
||||||
|
while True:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
value = n
|
||||||
|
n += step
|
||||||
|
await cancel_shielded_checkpoint()
|
||||||
|
yield value
|
||||||
|
|
||||||
|
|
||||||
|
async def cycle(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
) -> AsyncGenerator[T, None]:
|
||||||
|
saved: list[T] = []
|
||||||
|
async for element in _iterate(iterable):
|
||||||
|
saved.append(element)
|
||||||
|
yield element
|
||||||
|
|
||||||
|
if not saved:
|
||||||
|
await checkpoint()
|
||||||
|
return
|
||||||
|
|
||||||
|
while True:
|
||||||
|
for element in saved:
|
||||||
|
await checkpoint()
|
||||||
|
yield element
|
||||||
|
|
||||||
|
|
||||||
|
async def dropwhile(
|
||||||
|
predicate: Callable[[T], Awaitable[object]],
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
) -> AsyncGenerator[T, None]:
|
||||||
|
element_yielded = False
|
||||||
|
dropping = True
|
||||||
|
|
||||||
|
async for element in _iterate(iterable):
|
||||||
|
if dropping and await predicate(element):
|
||||||
|
continue
|
||||||
|
|
||||||
|
dropping = False
|
||||||
|
element_yielded = True
|
||||||
|
yield element
|
||||||
|
|
||||||
|
if not element_yielded:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
|
||||||
|
async def filterfalse(
|
||||||
|
predicate: Callable[[T], Awaitable[object]],
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
) -> AsyncGenerator[T, None]:
|
||||||
|
element_yielded = False
|
||||||
|
|
||||||
|
async for element in _iterate(iterable):
|
||||||
|
if not await predicate(element):
|
||||||
|
element_yielded = True
|
||||||
|
yield element
|
||||||
|
|
||||||
|
if not element_yielded:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def groupby(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
) -> AsyncGenerator[tuple[T, list[T]], None]: ...
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def groupby(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
key: Callable[[T], Awaitable[R]],
|
||||||
|
) -> AsyncGenerator[tuple[R, list[T]], None]: ...
|
||||||
|
|
||||||
|
|
||||||
|
async def groupby(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
key: Callable[[T], Awaitable[object]] | None = None,
|
||||||
|
) -> AsyncGenerator[tuple[object, list[T]], None]:
|
||||||
|
iterator = _iterate(iterable)
|
||||||
|
try:
|
||||||
|
element = await anext(iterator)
|
||||||
|
except StopAsyncIteration:
|
||||||
|
await checkpoint()
|
||||||
|
return
|
||||||
|
|
||||||
|
group_key = element if key is None else await key(element)
|
||||||
|
values = [element]
|
||||||
|
|
||||||
|
async for element in iterator:
|
||||||
|
next_key = element if key is None else await key(element)
|
||||||
|
if next_key != group_key:
|
||||||
|
completed_group = group_key, values
|
||||||
|
group_key = next_key
|
||||||
|
values = [element]
|
||||||
|
yield completed_group
|
||||||
|
else:
|
||||||
|
values.append(element)
|
||||||
|
|
||||||
|
yield group_key, values
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def islice(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
stop: int | None,
|
||||||
|
/,
|
||||||
|
) -> AsyncGenerator[T, None]: ...
|
||||||
|
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def islice(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
start: int | None,
|
||||||
|
stop: int | None,
|
||||||
|
step: int | None = 1,
|
||||||
|
/,
|
||||||
|
) -> AsyncGenerator[T, None]: ...
|
||||||
|
|
||||||
|
|
||||||
|
async def islice(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
*args: int | None,
|
||||||
|
) -> AsyncGenerator[T, None]:
|
||||||
|
if not args:
|
||||||
|
raise TypeError("islice expected at least 2 arguments, got 1")
|
||||||
|
if len(args) > 3:
|
||||||
|
raise TypeError(f"islice expected at most 4 arguments, got {len(args) + 1}")
|
||||||
|
|
||||||
|
slice_args = slice(*args)
|
||||||
|
|
||||||
|
start_message = (
|
||||||
|
"Indices for islice() must be None or an integer: 0 <= x <= sys.maxsize."
|
||||||
|
)
|
||||||
|
stop_message = (
|
||||||
|
"Stop argument for islice() must be None or an integer: 0 <= x <= sys.maxsize."
|
||||||
|
)
|
||||||
|
step_message = "Step for islice() must be a positive integer or None."
|
||||||
|
|
||||||
|
def normalize_index(value: object, message: str) -> int:
|
||||||
|
try:
|
||||||
|
index = operator.index(cast(Any, value))
|
||||||
|
except TypeError:
|
||||||
|
raise ValueError(message) from None
|
||||||
|
|
||||||
|
if index < 0 or index > sys.maxsize:
|
||||||
|
raise ValueError(message)
|
||||||
|
|
||||||
|
return index
|
||||||
|
|
||||||
|
start = (
|
||||||
|
0
|
||||||
|
if slice_args.start is None
|
||||||
|
else normalize_index(slice_args.start, start_message)
|
||||||
|
)
|
||||||
|
stop = (
|
||||||
|
None
|
||||||
|
if slice_args.stop is None
|
||||||
|
else normalize_index(slice_args.stop, stop_message)
|
||||||
|
)
|
||||||
|
step = (
|
||||||
|
1 if slice_args.step is None else normalize_index(slice_args.step, step_message)
|
||||||
|
)
|
||||||
|
|
||||||
|
if step <= 0:
|
||||||
|
raise ValueError(step_message)
|
||||||
|
|
||||||
|
if stop == 0 or start == stop:
|
||||||
|
await checkpoint()
|
||||||
|
return
|
||||||
|
|
||||||
|
iterator = _iterate(iterable)
|
||||||
|
index = 0
|
||||||
|
element_yielded = False
|
||||||
|
|
||||||
|
while stop is None or index < stop:
|
||||||
|
try:
|
||||||
|
element = await anext(iterator)
|
||||||
|
except StopAsyncIteration:
|
||||||
|
if not element_yielded:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
return
|
||||||
|
|
||||||
|
if index >= start and (index - start) % step == 0:
|
||||||
|
index += 1
|
||||||
|
element_yielded = True
|
||||||
|
yield element
|
||||||
|
else:
|
||||||
|
index += 1
|
||||||
|
|
||||||
|
if not element_yielded:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
|
||||||
|
async def pairwise(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
) -> AsyncGenerator[tuple[T, T], None]:
|
||||||
|
iterator = _iterate(iterable)
|
||||||
|
try:
|
||||||
|
previous = await anext(iterator)
|
||||||
|
except StopAsyncIteration:
|
||||||
|
await checkpoint()
|
||||||
|
return
|
||||||
|
|
||||||
|
element_yielded = False
|
||||||
|
async for element in iterator:
|
||||||
|
element_yielded = True
|
||||||
|
pair = (previous, element)
|
||||||
|
previous = element
|
||||||
|
yield pair
|
||||||
|
|
||||||
|
if not element_yielded:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
|
||||||
|
async def permutations(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T], r: int | None = None
|
||||||
|
) -> AsyncGenerator[tuple[T, ...], None]:
|
||||||
|
pool: list[T] = [element async for element in _iterate(iterable)]
|
||||||
|
n = len(pool)
|
||||||
|
if r is None:
|
||||||
|
r = n
|
||||||
|
elif not isinstance(r, int):
|
||||||
|
raise TypeError("Expected int as r")
|
||||||
|
elif r < 0:
|
||||||
|
raise ValueError("r must be non-negative")
|
||||||
|
|
||||||
|
async for permutation in _iterate(itertools.permutations(pool, r)):
|
||||||
|
yield permutation
|
||||||
|
|
||||||
|
|
||||||
|
async def product(
|
||||||
|
*iterables: Iterable[T] | AsyncIterable[T], repeat: int = 1
|
||||||
|
) -> AsyncGenerator[tuple[T, ...], None]:
|
||||||
|
repeat = operator.index(repeat)
|
||||||
|
if repeat < 0:
|
||||||
|
raise ValueError("repeat argument cannot be negative")
|
||||||
|
|
||||||
|
pools: list[tuple[T, ...]] = []
|
||||||
|
for iterable in iterables:
|
||||||
|
pool: list[T] = [element async for element in _iterate(iterable)]
|
||||||
|
pools.append(tuple(pool))
|
||||||
|
|
||||||
|
async for value in _iterate(itertools.product(*pools, repeat=repeat)):
|
||||||
|
yield value
|
||||||
|
|
||||||
|
|
||||||
|
async def repeat(element: T, times: int | None = None) -> AsyncGenerator[T, None]:
|
||||||
|
if times is None:
|
||||||
|
while True:
|
||||||
|
await checkpoint()
|
||||||
|
yield element
|
||||||
|
|
||||||
|
remaining = operator.index(cast(Any, times))
|
||||||
|
if remaining <= 0:
|
||||||
|
await checkpoint()
|
||||||
|
return
|
||||||
|
|
||||||
|
while remaining > 0:
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
remaining -= 1
|
||||||
|
await cancel_shielded_checkpoint()
|
||||||
|
yield element
|
||||||
|
|
||||||
|
|
||||||
|
async def starmap(
|
||||||
|
function: Callable[..., Awaitable[R]],
|
||||||
|
iterable: (
|
||||||
|
Iterable[Iterable[object] | AsyncIterable[object]]
|
||||||
|
| AsyncIterable[Iterable[object] | AsyncIterable[object]]
|
||||||
|
),
|
||||||
|
) -> AsyncGenerator[R, None]:
|
||||||
|
result_yielded = False
|
||||||
|
|
||||||
|
async for args_iterable in _iterate(iterable):
|
||||||
|
args = [element async for element in _iterate(args_iterable)]
|
||||||
|
result_yielded = True
|
||||||
|
yield await function(*args)
|
||||||
|
|
||||||
|
if not result_yielded:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
|
||||||
|
def tee(
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T], n: int = 2
|
||||||
|
) -> tuple[AsyncIterator[T], ...]:
|
||||||
|
n = operator.index(cast(Any, n))
|
||||||
|
if n < 0:
|
||||||
|
raise ValueError("n must be >= 0")
|
||||||
|
if n == 0:
|
||||||
|
return ()
|
||||||
|
|
||||||
|
iterator = _TeeAsyncIterator(iterable)
|
||||||
|
iterators: list[AsyncIterator[T]] = [iterator]
|
||||||
|
iterators.extend(_TeeAsyncIterator(iterator) for _ in range(n - 1))
|
||||||
|
return tuple(iterators)
|
||||||
|
|
||||||
|
|
||||||
|
async def takewhile(
|
||||||
|
predicate: Callable[[T], Awaitable[object]],
|
||||||
|
iterable: Iterable[T] | AsyncIterable[T],
|
||||||
|
) -> AsyncGenerator[T, None]:
|
||||||
|
element_yielded = False
|
||||||
|
|
||||||
|
async for element in _iterate(iterable):
|
||||||
|
if not await predicate(element):
|
||||||
|
if not element_yielded:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
return
|
||||||
|
|
||||||
|
element_yielded = True
|
||||||
|
yield element
|
||||||
|
|
||||||
|
if not element_yielded:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
|
||||||
|
async def zip_longest(
|
||||||
|
*iterables: Iterable[object] | AsyncIterable[object],
|
||||||
|
fillvalue: object = None,
|
||||||
|
) -> AsyncGenerator[tuple[object, ...], None]:
|
||||||
|
iterators = [_iterate(iterable) for iterable in iterables]
|
||||||
|
num_active = len(iterators)
|
||||||
|
if not num_active:
|
||||||
|
await checkpoint()
|
||||||
|
return
|
||||||
|
|
||||||
|
active = [True] * num_active
|
||||||
|
tuple_yielded = False
|
||||||
|
|
||||||
|
while True:
|
||||||
|
values: list[object] = []
|
||||||
|
for index, iterator in enumerate(iterators):
|
||||||
|
if not active[index]:
|
||||||
|
values.append(fillvalue)
|
||||||
|
continue
|
||||||
|
|
||||||
|
try:
|
||||||
|
value = await anext(iterator)
|
||||||
|
except StopAsyncIteration:
|
||||||
|
active[index] = False
|
||||||
|
num_active -= 1
|
||||||
|
if not num_active:
|
||||||
|
if not tuple_yielded:
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
return
|
||||||
|
|
||||||
|
value = fillvalue
|
||||||
|
|
||||||
|
values.append(value)
|
||||||
|
|
||||||
|
tuple_yielded = True
|
||||||
|
yield tuple(values)
|
||||||
@@ -0,0 +1,228 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"EventLoopToken",
|
||||||
|
"RunVar",
|
||||||
|
"RunvarToken",
|
||||||
|
"cancel_shielded_checkpoint",
|
||||||
|
"checkpoint",
|
||||||
|
"checkpoint_if_cancelled",
|
||||||
|
"current_token",
|
||||||
|
)
|
||||||
|
|
||||||
|
import enum
|
||||||
|
from dataclasses import dataclass
|
||||||
|
from types import TracebackType
|
||||||
|
from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, final, overload
|
||||||
|
from weakref import WeakKeyDictionary
|
||||||
|
|
||||||
|
from ._core._eventloop import get_async_backend
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
from .abc import AsyncBackend
|
||||||
|
|
||||||
|
T = TypeVar("T")
|
||||||
|
D = TypeVar("D")
|
||||||
|
|
||||||
|
|
||||||
|
async def checkpoint() -> None:
|
||||||
|
"""
|
||||||
|
Check for cancellation and allow the scheduler to switch to another task.
|
||||||
|
|
||||||
|
Equivalent to (but more efficient than)::
|
||||||
|
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
await cancel_shielded_checkpoint()
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
await get_async_backend().checkpoint()
|
||||||
|
|
||||||
|
|
||||||
|
async def checkpoint_if_cancelled() -> None:
|
||||||
|
"""
|
||||||
|
Enter a checkpoint if the enclosing cancel scope has been cancelled.
|
||||||
|
|
||||||
|
This does not allow the scheduler to switch to a different task.
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
await get_async_backend().checkpoint_if_cancelled()
|
||||||
|
|
||||||
|
|
||||||
|
async def cancel_shielded_checkpoint() -> None:
|
||||||
|
"""
|
||||||
|
Allow the scheduler to switch to another task but without checking for cancellation.
|
||||||
|
|
||||||
|
Equivalent to (but potentially more efficient than)::
|
||||||
|
|
||||||
|
with CancelScope(shield=True):
|
||||||
|
await checkpoint()
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
await get_async_backend().cancel_shielded_checkpoint()
|
||||||
|
|
||||||
|
|
||||||
|
@final
|
||||||
|
@dataclass(frozen=True, repr=False)
|
||||||
|
class EventLoopToken:
|
||||||
|
"""
|
||||||
|
An opaque object that holds a reference to an event loop.
|
||||||
|
|
||||||
|
.. versionadded:: 4.11.0
|
||||||
|
"""
|
||||||
|
|
||||||
|
backend_class: type[AsyncBackend]
|
||||||
|
native_token: object
|
||||||
|
|
||||||
|
|
||||||
|
def current_token() -> EventLoopToken:
|
||||||
|
"""
|
||||||
|
Return a token object that can be used to call code in the current event loop from
|
||||||
|
another thread.
|
||||||
|
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
.. versionadded:: 4.11.0
|
||||||
|
|
||||||
|
"""
|
||||||
|
backend_class = get_async_backend()
|
||||||
|
raw_token = backend_class.current_token()
|
||||||
|
return EventLoopToken(backend_class, raw_token)
|
||||||
|
|
||||||
|
|
||||||
|
_run_vars: WeakKeyDictionary[object, dict[RunVar[Any], Any]] = WeakKeyDictionary()
|
||||||
|
|
||||||
|
|
||||||
|
class _NoValueSet(enum.Enum):
|
||||||
|
NO_VALUE_SET = enum.auto()
|
||||||
|
|
||||||
|
|
||||||
|
class RunvarToken(Generic[T]):
|
||||||
|
"""
|
||||||
|
A token that can be used to restore a :class:`RunVar` to its previous value.
|
||||||
|
|
||||||
|
Returned by :meth:`RunVar.set`. Can be used as a context manager to automatically
|
||||||
|
reset the variable on exit, or passed directly to :meth:`RunVar.reset`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
__slots__ = "_redeemed", "_value", "_var"
|
||||||
|
|
||||||
|
def __init__(self, var: RunVar[T], value: T | Literal[_NoValueSet.NO_VALUE_SET]):
|
||||||
|
self._var = var
|
||||||
|
self._value: T | Literal[_NoValueSet.NO_VALUE_SET] = value
|
||||||
|
self._redeemed = False
|
||||||
|
|
||||||
|
def __enter__(self) -> RunvarToken[T]:
|
||||||
|
return self
|
||||||
|
|
||||||
|
def __exit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
self._var.reset(self)
|
||||||
|
|
||||||
|
|
||||||
|
class RunVar(Generic[T]):
|
||||||
|
"""
|
||||||
|
Like a :class:`~contextvars.ContextVar`, except scoped to the running event loop.
|
||||||
|
|
||||||
|
Can be used as a context manager, Just like :class:`~contextvars.ContextVar`, that
|
||||||
|
will reset the variable to its previous value when the context block is exited.
|
||||||
|
"""
|
||||||
|
|
||||||
|
__slots__ = "_default", "_name"
|
||||||
|
|
||||||
|
NO_VALUE_SET: Literal[_NoValueSet.NO_VALUE_SET] = _NoValueSet.NO_VALUE_SET
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self, name: str, default: T | Literal[_NoValueSet.NO_VALUE_SET] = NO_VALUE_SET
|
||||||
|
):
|
||||||
|
self._name = name
|
||||||
|
self._default = default
|
||||||
|
|
||||||
|
@property
|
||||||
|
def _current_vars(self) -> dict[RunVar[T], T]:
|
||||||
|
native_token = current_token().native_token
|
||||||
|
try:
|
||||||
|
return _run_vars[native_token]
|
||||||
|
except KeyError:
|
||||||
|
run_vars = _run_vars[native_token] = {}
|
||||||
|
return run_vars
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def get(self, default: D) -> T | D: ...
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def get(self) -> T: ...
|
||||||
|
|
||||||
|
def get(
|
||||||
|
self, default: D | Literal[_NoValueSet.NO_VALUE_SET] = NO_VALUE_SET
|
||||||
|
) -> T | D:
|
||||||
|
"""
|
||||||
|
Return the current value of this run variable.
|
||||||
|
|
||||||
|
:param default: a fallback value to return if no value has been set
|
||||||
|
:return: the current value, the provided default, or the variable's own default
|
||||||
|
:raises LookupError: if no value is set and no default is available
|
||||||
|
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
return self._current_vars[self]
|
||||||
|
except KeyError:
|
||||||
|
if default is not RunVar.NO_VALUE_SET:
|
||||||
|
return default
|
||||||
|
elif self._default is not RunVar.NO_VALUE_SET:
|
||||||
|
return self._default
|
||||||
|
|
||||||
|
raise LookupError(
|
||||||
|
f'Run variable "{self._name}" has no value and no default set'
|
||||||
|
)
|
||||||
|
|
||||||
|
def set(self, value: T) -> RunvarToken[T]:
|
||||||
|
"""
|
||||||
|
Set the value of this run variable for the current event loop.
|
||||||
|
|
||||||
|
:param value: the new value
|
||||||
|
:return: a token that can be used to restore the previous value
|
||||||
|
|
||||||
|
"""
|
||||||
|
current_vars = self._current_vars
|
||||||
|
token = RunvarToken(self, current_vars.get(self, RunVar.NO_VALUE_SET))
|
||||||
|
current_vars[self] = value
|
||||||
|
return token
|
||||||
|
|
||||||
|
def reset(self, token: RunvarToken[T]) -> None:
|
||||||
|
"""
|
||||||
|
Restore this run variable to the value it held before the matching :meth:`set`.
|
||||||
|
|
||||||
|
:param token: the token returned by :meth:`set`
|
||||||
|
:raises ValueError: if the token belongs to a different :class:`RunVar` or the token
|
||||||
|
has already been used
|
||||||
|
|
||||||
|
"""
|
||||||
|
if token._var is not self:
|
||||||
|
raise ValueError("This token does not belong to this RunVar")
|
||||||
|
|
||||||
|
if token._redeemed:
|
||||||
|
raise ValueError("This token has already been used")
|
||||||
|
|
||||||
|
if token._value is _NoValueSet.NO_VALUE_SET:
|
||||||
|
try:
|
||||||
|
del self._current_vars[self]
|
||||||
|
except KeyError:
|
||||||
|
pass
|
||||||
|
else:
|
||||||
|
self._current_vars[self] = token._value
|
||||||
|
|
||||||
|
token._redeemed = True
|
||||||
|
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
return f"<RunVar name={self._name!r}>"
|
||||||
Whitespace-only changes.
@@ -0,0 +1,404 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import dataclasses
|
||||||
|
import socket
|
||||||
|
import sys
|
||||||
|
from collections.abc import Callable, Generator, Iterator
|
||||||
|
from contextlib import ExitStack, contextmanager
|
||||||
|
from inspect import isasyncgenfunction, iscoroutinefunction, ismethod
|
||||||
|
from typing import TYPE_CHECKING, Any, cast
|
||||||
|
|
||||||
|
import pytest
|
||||||
|
from _pytest.fixtures import FuncFixtureInfo, SubRequest
|
||||||
|
from _pytest.outcomes import Exit
|
||||||
|
from _pytest.scope import Scope
|
||||||
|
|
||||||
|
from . import get_available_backends
|
||||||
|
from ._core._eventloop import (
|
||||||
|
current_async_library,
|
||||||
|
get_async_backend,
|
||||||
|
reset_current_async_library,
|
||||||
|
set_current_async_library,
|
||||||
|
)
|
||||||
|
from ._core._exceptions import iterate_exceptions
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
from .abc import TestRunner
|
||||||
|
|
||||||
|
if sys.version_info < (3, 11):
|
||||||
|
from exceptiongroup import ExceptionGroup
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
# pytest >= 9.2 keeps CallSpec2 as a TYPE_CHECKING-only alias of CallSpec
|
||||||
|
from _pytest.python import CallSpec2 as CallSpec
|
||||||
|
else:
|
||||||
|
try:
|
||||||
|
# c.f. https://github.com/pytest-dev/pytest/pull/14742
|
||||||
|
# pytest >= 9.2
|
||||||
|
from _pytest.python import CallSpec
|
||||||
|
except ImportError:
|
||||||
|
from _pytest.python import CallSpec2 as CallSpec
|
||||||
|
|
||||||
|
_current_runner: TestRunner | None = None
|
||||||
|
_runner_stack: ExitStack | None = None
|
||||||
|
_runner_leases = 0
|
||||||
|
|
||||||
|
|
||||||
|
def extract_backend_and_options(backend: object) -> tuple[str, dict[str, Any]]:
|
||||||
|
if isinstance(backend, str):
|
||||||
|
return backend, {}
|
||||||
|
elif isinstance(backend, tuple) and len(backend) == 2:
|
||||||
|
if isinstance(backend[0], str) and isinstance(backend[1], dict):
|
||||||
|
return cast(tuple[str, dict[str, Any]], backend)
|
||||||
|
|
||||||
|
raise TypeError("anyio_backend must be either a string or tuple of (string, dict)")
|
||||||
|
|
||||||
|
|
||||||
|
@contextmanager
|
||||||
|
def get_runner(
|
||||||
|
backend_name: str, backend_options: dict[str, Any]
|
||||||
|
) -> Iterator[TestRunner]:
|
||||||
|
global _current_runner, _runner_leases, _runner_stack
|
||||||
|
if _current_runner is None:
|
||||||
|
asynclib = get_async_backend(backend_name)
|
||||||
|
_runner_stack = ExitStack()
|
||||||
|
if current_async_library() is None:
|
||||||
|
# Since we're in control of the event loop, we can cache the name of the
|
||||||
|
# async library
|
||||||
|
token = set_current_async_library(backend_name)
|
||||||
|
_runner_stack.callback(reset_current_async_library, token)
|
||||||
|
|
||||||
|
backend_options = backend_options or {}
|
||||||
|
_current_runner = _runner_stack.enter_context(
|
||||||
|
asynclib.create_test_runner(backend_options)
|
||||||
|
)
|
||||||
|
|
||||||
|
_runner_leases += 1
|
||||||
|
try:
|
||||||
|
yield _current_runner
|
||||||
|
finally:
|
||||||
|
_runner_leases -= 1
|
||||||
|
if not _runner_leases:
|
||||||
|
assert _runner_stack is not None
|
||||||
|
_runner_stack.close()
|
||||||
|
_runner_stack = _current_runner = None
|
||||||
|
|
||||||
|
|
||||||
|
def pytest_addoption(parser: pytest.Parser) -> None:
|
||||||
|
group = parser.getgroup("anyio")
|
||||||
|
parser.addini(
|
||||||
|
"anyio_mode",
|
||||||
|
default="strict",
|
||||||
|
help='AnyIO plugin mode (either "strict" or "auto")',
|
||||||
|
)
|
||||||
|
group.addoption(
|
||||||
|
"--anyio-mode",
|
||||||
|
default=None,
|
||||||
|
dest="anyio_mode",
|
||||||
|
help="""
|
||||||
|
'auto' - All async test functions will be handled by AnyIO pytest plugin
|
||||||
|
'strict' - Disabling autoprocessing(useful when anyio tests
|
||||||
|
need to coexist with other async test plugins)
|
||||||
|
""",
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _is_auto_mode(config: pytest.Config, mode: str) -> bool:
|
||||||
|
return (
|
||||||
|
config.getoption(mode, default=None) == "auto" or config.getini(mode) == "auto"
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def pytest_configure(config: pytest.Config) -> None:
|
||||||
|
config.addinivalue_line(
|
||||||
|
"markers",
|
||||||
|
"anyio: mark the (coroutine function) test to be run asynchronously via anyio.",
|
||||||
|
)
|
||||||
|
if (
|
||||||
|
_is_auto_mode(config, "anyio_mode")
|
||||||
|
and config.pluginmanager.has_plugin("asyncio")
|
||||||
|
and _is_auto_mode(config, "asyncio_mode")
|
||||||
|
):
|
||||||
|
config.issue_config_time_warning(
|
||||||
|
pytest.PytestConfigWarning(
|
||||||
|
"AnyIO auto mode has been enabled together with pytest-asyncio auto "
|
||||||
|
"mode. This may cause unexpected behavior."
|
||||||
|
),
|
||||||
|
1,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.hookimpl(hookwrapper=True)
|
||||||
|
def pytest_fixture_setup(fixturedef: Any, request: Any) -> Generator[Any]:
|
||||||
|
def wrapper(anyio_backend: Any, request: SubRequest, **kwargs: Any) -> Any:
|
||||||
|
# Rebind any fixture methods to the request instance
|
||||||
|
if (
|
||||||
|
request.instance
|
||||||
|
and ismethod(func)
|
||||||
|
and type(func.__self__) is type(request.instance)
|
||||||
|
):
|
||||||
|
local_func = func.__func__.__get__(request.instance)
|
||||||
|
else:
|
||||||
|
local_func = func
|
||||||
|
|
||||||
|
backend_name, backend_options = extract_backend_and_options(anyio_backend)
|
||||||
|
if has_backend_arg:
|
||||||
|
kwargs["anyio_backend"] = anyio_backend
|
||||||
|
|
||||||
|
if has_request_arg:
|
||||||
|
kwargs["request"] = request
|
||||||
|
|
||||||
|
with get_runner(backend_name, backend_options) as runner:
|
||||||
|
# re-entrant call into the test runner detected. this happens when an async fixture
|
||||||
|
# is dynamically requested via request.getfixturevalue() from inside a running async
|
||||||
|
# test or fixture. on asyncio this raises RuntimeError: This event loop is already
|
||||||
|
# running, on trio the runner deadlocks - the host loop blocks waiting for the
|
||||||
|
# coroutine to return, but the coroutine is waiting for the host loop. raising here
|
||||||
|
# prevents the hang and gives a consistent error across backends.
|
||||||
|
if runner.is_running():
|
||||||
|
raise RuntimeError(
|
||||||
|
"Cannot schedule a coroutine in the test runner while another is already running; "
|
||||||
|
"likely caused by request.getfixturevalue() on an async fixture."
|
||||||
|
)
|
||||||
|
|
||||||
|
if isasyncgenfunction(local_func):
|
||||||
|
yield from runner.run_asyncgen_fixture(local_func, kwargs)
|
||||||
|
else:
|
||||||
|
yield runner.run_fixture(local_func, kwargs)
|
||||||
|
|
||||||
|
# Only apply this to coroutine functions and async generator functions in requests
|
||||||
|
# that involve the anyio_backend fixture
|
||||||
|
func = fixturedef.func
|
||||||
|
if isasyncgenfunction(func) or iscoroutinefunction(func):
|
||||||
|
if "anyio_backend" in request.fixturenames:
|
||||||
|
fixturedef.func = wrapper
|
||||||
|
original_argname = fixturedef.argnames
|
||||||
|
|
||||||
|
if not (has_backend_arg := "anyio_backend" in fixturedef.argnames):
|
||||||
|
fixturedef.argnames += ("anyio_backend",)
|
||||||
|
|
||||||
|
if not (has_request_arg := "request" in fixturedef.argnames):
|
||||||
|
fixturedef.argnames += ("request",)
|
||||||
|
|
||||||
|
try:
|
||||||
|
return (yield)
|
||||||
|
finally:
|
||||||
|
fixturedef.func = func
|
||||||
|
fixturedef.argnames = original_argname
|
||||||
|
|
||||||
|
return (yield)
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.hookimpl(tryfirst=True)
|
||||||
|
def pytest_pycollect_makeitem(
|
||||||
|
collector: pytest.Module | pytest.Class, name: str, obj: object
|
||||||
|
) -> None:
|
||||||
|
if collector.istestfunction(obj, name):
|
||||||
|
inner_func = obj.hypothesis.inner_test if hasattr(obj, "hypothesis") else obj
|
||||||
|
if iscoroutinefunction(inner_func):
|
||||||
|
anyio_auto_mode = _is_auto_mode(collector.config, "anyio_mode")
|
||||||
|
marker = collector.get_closest_marker("anyio")
|
||||||
|
own_markers = getattr(obj, "pytestmark", ())
|
||||||
|
if (
|
||||||
|
anyio_auto_mode
|
||||||
|
or marker
|
||||||
|
or any(marker.name == "anyio" for marker in own_markers)
|
||||||
|
):
|
||||||
|
pytest.mark.usefixtures("anyio_backend")(obj)
|
||||||
|
|
||||||
|
|
||||||
|
def pytest_collection_finish(session: pytest.Session) -> None:
|
||||||
|
for i, item in reversed(list(enumerate(session.items))):
|
||||||
|
if (
|
||||||
|
isinstance(item, pytest.Function)
|
||||||
|
and iscoroutinefunction(item.function)
|
||||||
|
and item.get_closest_marker("anyio") is not None
|
||||||
|
and "anyio_backend" not in item.fixturenames
|
||||||
|
):
|
||||||
|
new_items = []
|
||||||
|
try:
|
||||||
|
cs_fields = {f.name for f in dataclasses.fields(CallSpec)}
|
||||||
|
except TypeError:
|
||||||
|
cs_fields = set()
|
||||||
|
|
||||||
|
for param_index, backend in enumerate(get_available_backends()):
|
||||||
|
if "_arg2scope" in cs_fields: # pytest >= 8
|
||||||
|
callspec = CallSpec(
|
||||||
|
params={"anyio_backend": backend},
|
||||||
|
indices={"anyio_backend": param_index},
|
||||||
|
_arg2scope={"anyio_backend": Scope.Module},
|
||||||
|
_idlist=[backend],
|
||||||
|
marks=[],
|
||||||
|
)
|
||||||
|
else: # pytest 7.x
|
||||||
|
callspec = CallSpec( # type: ignore[call-arg]
|
||||||
|
funcargs={},
|
||||||
|
params={"anyio_backend": backend},
|
||||||
|
indices={"anyio_backend": param_index},
|
||||||
|
arg2scope={"anyio_backend": Scope.Module},
|
||||||
|
idlist=[backend],
|
||||||
|
marks=[],
|
||||||
|
)
|
||||||
|
|
||||||
|
fi = item._fixtureinfo
|
||||||
|
new_names_closure = list(fi.names_closure)
|
||||||
|
if "anyio_backend" not in new_names_closure:
|
||||||
|
new_names_closure.append("anyio_backend")
|
||||||
|
|
||||||
|
new_fixtureinfo = FuncFixtureInfo(
|
||||||
|
argnames=fi.argnames,
|
||||||
|
initialnames=fi.initialnames,
|
||||||
|
names_closure=new_names_closure,
|
||||||
|
name2fixturedefs=fi.name2fixturedefs,
|
||||||
|
)
|
||||||
|
new_item = pytest.Function.from_parent(
|
||||||
|
item.parent,
|
||||||
|
name=f"{item.originalname}[{backend}]",
|
||||||
|
callspec=callspec,
|
||||||
|
callobj=item.obj,
|
||||||
|
fixtureinfo=new_fixtureinfo,
|
||||||
|
keywords=item.keywords,
|
||||||
|
originalname=item.originalname,
|
||||||
|
)
|
||||||
|
new_items.append(new_item)
|
||||||
|
|
||||||
|
session.items[i : i + 1] = new_items
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.hookimpl(tryfirst=True)
|
||||||
|
def pytest_pyfunc_call(pyfuncitem: Any) -> bool | None:
|
||||||
|
def run_with_hypothesis(**kwargs: Any) -> None:
|
||||||
|
with get_runner(backend_name, backend_options) as runner:
|
||||||
|
runner.run_test(original_func, kwargs)
|
||||||
|
|
||||||
|
backend = pyfuncitem.funcargs.get("anyio_backend")
|
||||||
|
if backend:
|
||||||
|
backend_name, backend_options = extract_backend_and_options(backend)
|
||||||
|
|
||||||
|
if hasattr(pyfuncitem.obj, "hypothesis"):
|
||||||
|
# Wrap the inner test function unless it's already wrapped
|
||||||
|
original_func = pyfuncitem.obj.hypothesis.inner_test
|
||||||
|
if original_func.__qualname__ != run_with_hypothesis.__qualname__:
|
||||||
|
if iscoroutinefunction(original_func):
|
||||||
|
pyfuncitem.obj.hypothesis.inner_test = run_with_hypothesis
|
||||||
|
|
||||||
|
return None
|
||||||
|
|
||||||
|
if iscoroutinefunction(pyfuncitem.obj):
|
||||||
|
funcargs = pyfuncitem.funcargs
|
||||||
|
testargs = {arg: funcargs[arg] for arg in pyfuncitem._fixtureinfo.argnames}
|
||||||
|
with get_runner(backend_name, backend_options) as runner:
|
||||||
|
try:
|
||||||
|
runner.run_test(pyfuncitem.obj, testargs)
|
||||||
|
except ExceptionGroup as excgrp:
|
||||||
|
for exc in iterate_exceptions(excgrp):
|
||||||
|
if isinstance(exc, (Exit, KeyboardInterrupt, SystemExit)):
|
||||||
|
raise exc from excgrp
|
||||||
|
|
||||||
|
raise
|
||||||
|
|
||||||
|
return True
|
||||||
|
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture(scope="module", params=get_available_backends())
|
||||||
|
def anyio_backend(request: Any) -> Any:
|
||||||
|
return request.param
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def anyio_backend_name(anyio_backend: Any) -> str:
|
||||||
|
if isinstance(anyio_backend, str):
|
||||||
|
return anyio_backend
|
||||||
|
else:
|
||||||
|
return anyio_backend[0]
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def anyio_backend_options(anyio_backend: Any) -> dict[str, Any]:
|
||||||
|
if isinstance(anyio_backend, str):
|
||||||
|
return {}
|
||||||
|
else:
|
||||||
|
return anyio_backend[1]
|
||||||
|
|
||||||
|
|
||||||
|
class FreePortFactory:
|
||||||
|
"""
|
||||||
|
Manages port generation based on specified socket kind, ensuring no duplicate
|
||||||
|
ports are generated.
|
||||||
|
|
||||||
|
This class provides functionality for generating available free ports on the
|
||||||
|
system. It is initialized with a specific socket kind and can generate ports
|
||||||
|
for given address families while avoiding reuse of previously generated ports.
|
||||||
|
|
||||||
|
Users should not instantiate this class directly, but use the
|
||||||
|
``free_tcp_port_factory`` and ``free_udp_port_factory`` fixtures instead. For simple
|
||||||
|
uses cases, ``free_tcp_port`` and ``free_udp_port`` can be used instead.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, kind: socket.SocketKind) -> None:
|
||||||
|
self._kind = kind
|
||||||
|
self._generated = set[int]()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def kind(self) -> socket.SocketKind:
|
||||||
|
"""
|
||||||
|
The type of socket connection (e.g., :data:`~socket.SOCK_STREAM` or
|
||||||
|
:data:`~socket.SOCK_DGRAM`) used to bind for checking port availability
|
||||||
|
|
||||||
|
"""
|
||||||
|
return self._kind
|
||||||
|
|
||||||
|
def __call__(self, family: socket.AddressFamily | None = None) -> int:
|
||||||
|
"""
|
||||||
|
Return an unbound port for the given address family.
|
||||||
|
|
||||||
|
:param family: if omitted, both IPv4 and IPv6 addresses will be tried
|
||||||
|
:return: a port number
|
||||||
|
|
||||||
|
"""
|
||||||
|
if family is not None:
|
||||||
|
families = [family]
|
||||||
|
else:
|
||||||
|
families = [socket.AF_INET]
|
||||||
|
if socket.has_ipv6:
|
||||||
|
families.append(socket.AF_INET6)
|
||||||
|
|
||||||
|
while True:
|
||||||
|
port = 0
|
||||||
|
with ExitStack() as stack:
|
||||||
|
for fam in families:
|
||||||
|
sock = stack.enter_context(socket.socket(fam, self._kind))
|
||||||
|
addr = "::1" if fam == socket.AF_INET6 else "127.0.0.1"
|
||||||
|
try:
|
||||||
|
sock.bind((addr, port))
|
||||||
|
except OSError:
|
||||||
|
break
|
||||||
|
|
||||||
|
if not port:
|
||||||
|
port = sock.getsockname()[1]
|
||||||
|
else:
|
||||||
|
if port not in self._generated:
|
||||||
|
self._generated.add(port)
|
||||||
|
return port
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture(scope="session")
|
||||||
|
def free_tcp_port_factory() -> FreePortFactory:
|
||||||
|
return FreePortFactory(socket.SOCK_STREAM)
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture(scope="session")
|
||||||
|
def free_udp_port_factory() -> FreePortFactory:
|
||||||
|
return FreePortFactory(socket.SOCK_DGRAM)
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def free_tcp_port(free_tcp_port_factory: Callable[[], int]) -> int:
|
||||||
|
return free_tcp_port_factory()
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture
|
||||||
|
def free_udp_port(free_udp_port_factory: Callable[[], int]) -> int:
|
||||||
|
return free_udp_port_factory()
|
||||||
Whitespace-only changes.
@@ -0,0 +1,201 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"BufferedByteReceiveStream",
|
||||||
|
"BufferedByteStream",
|
||||||
|
"BufferedConnectable",
|
||||||
|
)
|
||||||
|
|
||||||
|
import sys
|
||||||
|
from collections.abc import Callable, Iterable, Mapping
|
||||||
|
from dataclasses import dataclass, field
|
||||||
|
from typing import Any, SupportsIndex
|
||||||
|
|
||||||
|
from .. import ClosedResourceError, DelimiterNotFound, EndOfStream, IncompleteRead
|
||||||
|
from ..abc import (
|
||||||
|
AnyByteReceiveStream,
|
||||||
|
AnyByteStream,
|
||||||
|
AnyByteStreamConnectable,
|
||||||
|
ByteReceiveStream,
|
||||||
|
ByteStream,
|
||||||
|
ByteStreamConnectable,
|
||||||
|
)
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 12):
|
||||||
|
from typing import override
|
||||||
|
else:
|
||||||
|
from typing_extensions import override
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class BufferedByteReceiveStream(ByteReceiveStream):
|
||||||
|
"""
|
||||||
|
Wraps any bytes-based receive stream and uses a buffer to provide sophisticated
|
||||||
|
receiving capabilities in the form of a byte stream.
|
||||||
|
"""
|
||||||
|
|
||||||
|
receive_stream: AnyByteReceiveStream
|
||||||
|
_buffer: bytearray = field(init=False, default_factory=bytearray)
|
||||||
|
_closed: bool = field(init=False, default=False)
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
await self.receive_stream.aclose()
|
||||||
|
self._closed = True
|
||||||
|
|
||||||
|
@property
|
||||||
|
def buffer(self) -> bytes:
|
||||||
|
"""The bytes currently in the buffer."""
|
||||||
|
return bytes(self._buffer)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def extra_attributes(self) -> Mapping[Any, Callable[[], Any]]:
|
||||||
|
return self.receive_stream.extra_attributes
|
||||||
|
|
||||||
|
def feed_data(self, data: Iterable[SupportsIndex], /) -> None:
|
||||||
|
"""
|
||||||
|
Append data directly into the buffer.
|
||||||
|
|
||||||
|
Any data in the buffer will be consumed by receive operations before receiving
|
||||||
|
anything from the wrapped stream.
|
||||||
|
|
||||||
|
:param data: the data to append to the buffer (can be bytes or anything else
|
||||||
|
that supports ``__index__()``)
|
||||||
|
|
||||||
|
"""
|
||||||
|
self._buffer.extend(data)
|
||||||
|
|
||||||
|
async def receive(self, max_bytes: int = 65536) -> bytes:
|
||||||
|
if max_bytes < 1:
|
||||||
|
raise ValueError("max_bytes must be a positive integer")
|
||||||
|
|
||||||
|
if self._closed:
|
||||||
|
raise ClosedResourceError
|
||||||
|
|
||||||
|
if self._buffer:
|
||||||
|
chunk = bytes(self._buffer[:max_bytes])
|
||||||
|
del self._buffer[:max_bytes]
|
||||||
|
return chunk
|
||||||
|
elif isinstance(self.receive_stream, ByteReceiveStream):
|
||||||
|
return await self.receive_stream.receive(max_bytes)
|
||||||
|
else:
|
||||||
|
# With a bytes-oriented object stream, we need to handle any surplus bytes
|
||||||
|
# we get from the receive() call
|
||||||
|
chunk = await self.receive_stream.receive()
|
||||||
|
if len(chunk) > max_bytes:
|
||||||
|
# Save the surplus bytes in the buffer
|
||||||
|
self._buffer.extend(chunk[max_bytes:])
|
||||||
|
return chunk[:max_bytes]
|
||||||
|
else:
|
||||||
|
return chunk
|
||||||
|
|
||||||
|
async def receive_exactly(self, nbytes: int) -> bytes:
|
||||||
|
"""
|
||||||
|
Read exactly the given amount of bytes from the stream.
|
||||||
|
|
||||||
|
:param nbytes: the number of bytes to read
|
||||||
|
:return: the bytes read
|
||||||
|
:raises ~anyio.IncompleteRead: if the stream was closed before the requested
|
||||||
|
amount of bytes could be read from the stream
|
||||||
|
|
||||||
|
"""
|
||||||
|
while True:
|
||||||
|
remaining = nbytes - len(self._buffer)
|
||||||
|
if remaining <= 0:
|
||||||
|
retval = self._buffer[:nbytes]
|
||||||
|
del self._buffer[:nbytes]
|
||||||
|
return bytes(retval)
|
||||||
|
|
||||||
|
try:
|
||||||
|
if isinstance(self.receive_stream, ByteReceiveStream):
|
||||||
|
chunk = await self.receive_stream.receive(remaining)
|
||||||
|
else:
|
||||||
|
chunk = await self.receive_stream.receive()
|
||||||
|
except EndOfStream as exc:
|
||||||
|
raise IncompleteRead from exc
|
||||||
|
|
||||||
|
self._buffer.extend(chunk)
|
||||||
|
|
||||||
|
async def receive_until(self, delimiter: bytes, max_bytes: int) -> bytes:
|
||||||
|
"""
|
||||||
|
Read from the stream until the delimiter is found or max_bytes have been read.
|
||||||
|
|
||||||
|
:param delimiter: the marker to look for in the stream
|
||||||
|
:param max_bytes: maximum number of bytes that will be read before raising
|
||||||
|
:exc:`~anyio.DelimiterNotFound`
|
||||||
|
:return: the bytes read (not including the delimiter)
|
||||||
|
:raises ~anyio.IncompleteRead: if the stream was closed before the delimiter
|
||||||
|
was found
|
||||||
|
:raises ~anyio.DelimiterNotFound: if the delimiter is not found within the
|
||||||
|
bytes read up to the maximum allowed
|
||||||
|
|
||||||
|
"""
|
||||||
|
delimiter_size = len(delimiter)
|
||||||
|
offset = 0
|
||||||
|
while True:
|
||||||
|
# Check if the delimiter can be found in the current buffer
|
||||||
|
index = self._buffer.find(delimiter, offset)
|
||||||
|
if index >= 0:
|
||||||
|
found = self._buffer[:index]
|
||||||
|
del self._buffer[: index + len(delimiter) :]
|
||||||
|
return bytes(found)
|
||||||
|
|
||||||
|
# Check if the buffer is already at or over the limit
|
||||||
|
if len(self._buffer) >= max_bytes:
|
||||||
|
raise DelimiterNotFound(max_bytes)
|
||||||
|
|
||||||
|
# Read more data into the buffer from the socket
|
||||||
|
try:
|
||||||
|
data = await self.receive_stream.receive()
|
||||||
|
except EndOfStream as exc:
|
||||||
|
raise IncompleteRead from exc
|
||||||
|
|
||||||
|
# Move the offset forward and add the new data to the buffer
|
||||||
|
offset = max(len(self._buffer) - delimiter_size + 1, 0)
|
||||||
|
self._buffer.extend(data)
|
||||||
|
|
||||||
|
|
||||||
|
class BufferedByteStream(BufferedByteReceiveStream, ByteStream):
|
||||||
|
"""
|
||||||
|
A full-duplex variant of :class:`BufferedByteReceiveStream`. All writes are passed
|
||||||
|
through to the wrapped stream as-is.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, stream: AnyByteStream):
|
||||||
|
"""
|
||||||
|
:param stream: the stream to be wrapped
|
||||||
|
|
||||||
|
"""
|
||||||
|
super().__init__(stream)
|
||||||
|
self._stream = stream
|
||||||
|
|
||||||
|
@override
|
||||||
|
async def send_eof(self) -> None:
|
||||||
|
await self._stream.send_eof()
|
||||||
|
|
||||||
|
@override
|
||||||
|
async def send(self, item: bytes) -> None:
|
||||||
|
await self._stream.send(item)
|
||||||
|
|
||||||
|
|
||||||
|
class BufferedConnectable(ByteStreamConnectable):
|
||||||
|
"""
|
||||||
|
Wraps a byte stream connectable to produce :class:`BufferedByteStream` connections.
|
||||||
|
|
||||||
|
Use this when you want the streams returned by :meth:`connect` to have the buffered
|
||||||
|
receive API (e.g. :meth:`~BufferedByteReceiveStream.receive_exactly` and
|
||||||
|
:meth:`~BufferedByteReceiveStream.receive_until`).
|
||||||
|
|
||||||
|
:param connectable: the byte stream connectable to wrap
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, connectable: AnyByteStreamConnectable):
|
||||||
|
"""
|
||||||
|
:param connectable: the connectable to wrap
|
||||||
|
|
||||||
|
"""
|
||||||
|
self.connectable = connectable
|
||||||
|
|
||||||
|
@override
|
||||||
|
async def connect(self) -> BufferedByteStream:
|
||||||
|
stream = await self.connectable.connect()
|
||||||
|
return BufferedByteStream(stream)
|
||||||
@@ -0,0 +1,157 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"FileReadStream",
|
||||||
|
"FileStreamAttribute",
|
||||||
|
"FileWriteStream",
|
||||||
|
)
|
||||||
|
|
||||||
|
from collections.abc import Callable, Mapping
|
||||||
|
from io import SEEK_SET, UnsupportedOperation
|
||||||
|
from os import PathLike
|
||||||
|
from pathlib import Path
|
||||||
|
from typing import IO, Any
|
||||||
|
|
||||||
|
from .. import (
|
||||||
|
BrokenResourceError,
|
||||||
|
ClosedResourceError,
|
||||||
|
EndOfStream,
|
||||||
|
TypedAttributeSet,
|
||||||
|
to_thread,
|
||||||
|
typed_attribute,
|
||||||
|
)
|
||||||
|
from ..abc import ByteReceiveStream, ByteSendStream
|
||||||
|
|
||||||
|
|
||||||
|
class FileStreamAttribute(TypedAttributeSet):
|
||||||
|
#: the open file descriptor
|
||||||
|
file: IO[bytes] = typed_attribute()
|
||||||
|
#: the path of the file on the file system, if available (file must be a real file)
|
||||||
|
path: Path = typed_attribute()
|
||||||
|
#: the file number, if available (file must be a real file or a TTY)
|
||||||
|
fileno: int = typed_attribute()
|
||||||
|
|
||||||
|
|
||||||
|
class _BaseFileStream:
|
||||||
|
def __init__(self, file: IO[bytes]):
|
||||||
|
self._file = file
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
await to_thread.run_sync(self._file.close)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def extra_attributes(self) -> Mapping[Any, Callable[[], Any]]:
|
||||||
|
attributes: dict[Any, Callable[[], Any]] = {
|
||||||
|
FileStreamAttribute.file: lambda: self._file,
|
||||||
|
}
|
||||||
|
|
||||||
|
if hasattr(self._file, "name"):
|
||||||
|
attributes[FileStreamAttribute.path] = lambda: Path(self._file.name)
|
||||||
|
|
||||||
|
try:
|
||||||
|
self._file.fileno()
|
||||||
|
except UnsupportedOperation:
|
||||||
|
pass
|
||||||
|
else:
|
||||||
|
attributes[FileStreamAttribute.fileno] = lambda: self._file.fileno()
|
||||||
|
|
||||||
|
return attributes
|
||||||
|
|
||||||
|
|
||||||
|
class FileReadStream(_BaseFileStream, ByteReceiveStream):
|
||||||
|
"""
|
||||||
|
A byte stream that reads from a file in the file system.
|
||||||
|
|
||||||
|
:param file: a file that has been opened for reading in binary mode
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
async def from_path(cls, path: str | PathLike[str]) -> FileReadStream:
|
||||||
|
"""
|
||||||
|
Create a file read stream by opening the given file.
|
||||||
|
|
||||||
|
:param path: path of the file to read from
|
||||||
|
|
||||||
|
"""
|
||||||
|
file = await to_thread.run_sync(Path(path).open, "rb")
|
||||||
|
return cls(file)
|
||||||
|
|
||||||
|
async def receive(self, max_bytes: int = 65536) -> bytes:
|
||||||
|
if max_bytes < 1:
|
||||||
|
raise ValueError("max_bytes must be a positive integer")
|
||||||
|
|
||||||
|
try:
|
||||||
|
data = await to_thread.run_sync(self._file.read, max_bytes)
|
||||||
|
except ValueError:
|
||||||
|
raise ClosedResourceError from None
|
||||||
|
except OSError as exc:
|
||||||
|
raise BrokenResourceError from exc
|
||||||
|
|
||||||
|
if data:
|
||||||
|
return data
|
||||||
|
else:
|
||||||
|
raise EndOfStream
|
||||||
|
|
||||||
|
async def seek(self, position: int, whence: int = SEEK_SET) -> int:
|
||||||
|
"""
|
||||||
|
Seek the file to the given position.
|
||||||
|
|
||||||
|
.. seealso:: :meth:`io.IOBase.seek`
|
||||||
|
|
||||||
|
.. note:: Not all file descriptors are seekable.
|
||||||
|
|
||||||
|
:param position: position to seek the file to
|
||||||
|
:param whence: controls how ``position`` is interpreted
|
||||||
|
:return: the new absolute position
|
||||||
|
:raises OSError: if the file is not seekable
|
||||||
|
|
||||||
|
"""
|
||||||
|
return await to_thread.run_sync(self._file.seek, position, whence)
|
||||||
|
|
||||||
|
async def tell(self) -> int:
|
||||||
|
"""
|
||||||
|
Return the current stream position.
|
||||||
|
|
||||||
|
.. note:: Not all file descriptors are seekable.
|
||||||
|
|
||||||
|
:return: the current absolute position
|
||||||
|
:raises OSError: if the file is not seekable
|
||||||
|
|
||||||
|
"""
|
||||||
|
return await to_thread.run_sync(self._file.tell)
|
||||||
|
|
||||||
|
|
||||||
|
class FileWriteStream(_BaseFileStream, ByteSendStream):
|
||||||
|
"""
|
||||||
|
A byte stream that writes to a file in the file system.
|
||||||
|
|
||||||
|
:param file: a file that has been opened for writing in binary mode
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
"""
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
async def from_path(
|
||||||
|
cls, path: str | PathLike[str], append: bool = False
|
||||||
|
) -> FileWriteStream:
|
||||||
|
"""
|
||||||
|
Create a file write stream by opening the given file for writing.
|
||||||
|
|
||||||
|
:param path: path of the file to write to
|
||||||
|
:param append: if ``True``, open the file for appending; if ``False``, any
|
||||||
|
existing file at the given path will be truncated
|
||||||
|
|
||||||
|
"""
|
||||||
|
mode = "ab" if append else "wb"
|
||||||
|
file = await to_thread.run_sync(Path(path).open, mode)
|
||||||
|
return cls(file)
|
||||||
|
|
||||||
|
async def send(self, item: bytes) -> None:
|
||||||
|
try:
|
||||||
|
await to_thread.run_sync(self._file.write, item)
|
||||||
|
except ValueError:
|
||||||
|
raise ClosedResourceError from None
|
||||||
|
except OSError as exc:
|
||||||
|
raise BrokenResourceError from exc
|
||||||
@@ -0,0 +1,326 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"MemoryObjectReceiveStream",
|
||||||
|
"MemoryObjectSendStream",
|
||||||
|
"MemoryObjectStreamStatistics",
|
||||||
|
)
|
||||||
|
|
||||||
|
import warnings
|
||||||
|
from collections import OrderedDict, deque
|
||||||
|
from dataclasses import dataclass, field
|
||||||
|
from types import TracebackType
|
||||||
|
from typing import Generic, NamedTuple, TypeVar
|
||||||
|
|
||||||
|
from .._core._exceptions import (
|
||||||
|
BrokenResourceError,
|
||||||
|
ClosedResourceError,
|
||||||
|
EndOfStream,
|
||||||
|
WouldBlock,
|
||||||
|
)
|
||||||
|
from .._core._synchronization import Event
|
||||||
|
from .._core._testing import TaskInfo, get_current_task
|
||||||
|
from ..abc import ObjectReceiveStream, ObjectSendStream
|
||||||
|
from ..lowlevel import checkpoint
|
||||||
|
|
||||||
|
T_Item = TypeVar("T_Item")
|
||||||
|
T_co = TypeVar("T_co", covariant=True)
|
||||||
|
T_contra = TypeVar("T_contra", contravariant=True)
|
||||||
|
|
||||||
|
|
||||||
|
class MemoryObjectStreamStatistics(NamedTuple):
|
||||||
|
current_buffer_used: int #: number of items stored in the buffer
|
||||||
|
#: maximum number of items that can be stored on this stream (or :data:`math.inf`)
|
||||||
|
max_buffer_size: float
|
||||||
|
open_send_streams: int #: number of unclosed clones of the send stream
|
||||||
|
open_receive_streams: int #: number of unclosed clones of the receive stream
|
||||||
|
#: number of tasks blocked on :meth:`MemoryObjectSendStream.send`
|
||||||
|
tasks_waiting_send: int
|
||||||
|
#: number of tasks blocked on :meth:`MemoryObjectReceiveStream.receive`
|
||||||
|
tasks_waiting_receive: int
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class _MemoryObjectItemReceiver(Generic[T_Item]):
|
||||||
|
task_info: TaskInfo = field(init=False, default_factory=get_current_task)
|
||||||
|
item: T_Item = field(init=False)
|
||||||
|
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
# When item is not defined, we get following error with default __repr__:
|
||||||
|
# AttributeError: 'MemoryObjectItemReceiver' object has no attribute 'item'
|
||||||
|
item = getattr(self, "item", None)
|
||||||
|
return f"{self.__class__.__name__}(task_info={self.task_info}, item={item!r})"
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class _MemoryObjectStreamState(Generic[T_Item]):
|
||||||
|
max_buffer_size: float = field()
|
||||||
|
buffer: deque[T_Item] = field(init=False, default_factory=deque)
|
||||||
|
open_send_channels: int = field(init=False, default=0)
|
||||||
|
open_receive_channels: int = field(init=False, default=0)
|
||||||
|
waiting_receivers: OrderedDict[Event, _MemoryObjectItemReceiver[T_Item]] = field(
|
||||||
|
init=False, default_factory=OrderedDict
|
||||||
|
)
|
||||||
|
waiting_senders: OrderedDict[Event, T_Item] = field(
|
||||||
|
init=False, default_factory=OrderedDict
|
||||||
|
)
|
||||||
|
|
||||||
|
def statistics(self) -> MemoryObjectStreamStatistics:
|
||||||
|
return MemoryObjectStreamStatistics(
|
||||||
|
len(self.buffer),
|
||||||
|
self.max_buffer_size,
|
||||||
|
self.open_send_channels,
|
||||||
|
self.open_receive_channels,
|
||||||
|
len(self.waiting_senders),
|
||||||
|
len(self.waiting_receivers),
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class MemoryObjectReceiveStream(ObjectReceiveStream[T_co], Generic[T_co]):
|
||||||
|
_state: _MemoryObjectStreamState[T_co]
|
||||||
|
_closed: bool = field(init=False, default=False)
|
||||||
|
|
||||||
|
def __post_init__(self) -> None:
|
||||||
|
self._state.open_receive_channels += 1
|
||||||
|
|
||||||
|
def receive_nowait(self) -> T_co:
|
||||||
|
"""
|
||||||
|
Receive the next item if it can be done without waiting.
|
||||||
|
|
||||||
|
:return: the received item
|
||||||
|
:raises ~anyio.ClosedResourceError: if this send stream has been closed
|
||||||
|
:raises ~anyio.EndOfStream: if the buffer is empty and this stream has been
|
||||||
|
closed from the sending end
|
||||||
|
:raises ~anyio.WouldBlock: if there are no items in the buffer and no tasks
|
||||||
|
waiting to send
|
||||||
|
|
||||||
|
"""
|
||||||
|
if self._closed:
|
||||||
|
raise ClosedResourceError
|
||||||
|
|
||||||
|
if self._state.waiting_senders:
|
||||||
|
# Get the item from the next sender
|
||||||
|
send_event, item = self._state.waiting_senders.popitem(last=False)
|
||||||
|
self._state.buffer.append(item)
|
||||||
|
send_event.set()
|
||||||
|
|
||||||
|
if self._state.buffer:
|
||||||
|
return self._state.buffer.popleft()
|
||||||
|
elif not self._state.open_send_channels:
|
||||||
|
raise EndOfStream
|
||||||
|
|
||||||
|
raise WouldBlock
|
||||||
|
|
||||||
|
async def receive(self) -> T_co:
|
||||||
|
await checkpoint()
|
||||||
|
try:
|
||||||
|
return self.receive_nowait()
|
||||||
|
except WouldBlock:
|
||||||
|
# Add ourselves in the queue
|
||||||
|
receive_event = Event()
|
||||||
|
receiver = _MemoryObjectItemReceiver[T_co]()
|
||||||
|
self._state.waiting_receivers[receive_event] = receiver
|
||||||
|
|
||||||
|
try:
|
||||||
|
await receive_event.wait()
|
||||||
|
finally:
|
||||||
|
self._state.waiting_receivers.pop(receive_event, None)
|
||||||
|
|
||||||
|
try:
|
||||||
|
return receiver.item
|
||||||
|
except AttributeError:
|
||||||
|
raise EndOfStream from None
|
||||||
|
|
||||||
|
def clone(self) -> MemoryObjectReceiveStream[T_co]:
|
||||||
|
"""
|
||||||
|
Create a clone of this receive stream.
|
||||||
|
|
||||||
|
Each clone can be closed separately. Only when all clones have been closed will
|
||||||
|
the receiving end of the memory stream be considered closed by the sending ends.
|
||||||
|
|
||||||
|
:return: the cloned stream
|
||||||
|
|
||||||
|
"""
|
||||||
|
if self._closed:
|
||||||
|
raise ClosedResourceError
|
||||||
|
|
||||||
|
return MemoryObjectReceiveStream(_state=self._state)
|
||||||
|
|
||||||
|
def close(self) -> None:
|
||||||
|
"""
|
||||||
|
Close the stream.
|
||||||
|
|
||||||
|
This works the exact same way as :meth:`aclose`, but is provided as a special
|
||||||
|
case for the benefit of synchronous callbacks.
|
||||||
|
|
||||||
|
"""
|
||||||
|
if not self._closed:
|
||||||
|
self._closed = True
|
||||||
|
self._state.open_receive_channels -= 1
|
||||||
|
if self._state.open_receive_channels == 0:
|
||||||
|
send_events = list(self._state.waiting_senders.keys())
|
||||||
|
for event in send_events:
|
||||||
|
event.set()
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
self.close()
|
||||||
|
|
||||||
|
def statistics(self) -> MemoryObjectStreamStatistics:
|
||||||
|
"""
|
||||||
|
Return statistics about the current state of this stream.
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
"""
|
||||||
|
return self._state.statistics()
|
||||||
|
|
||||||
|
def __enter__(self) -> MemoryObjectReceiveStream[T_co]:
|
||||||
|
return self
|
||||||
|
|
||||||
|
def __exit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
self.close()
|
||||||
|
|
||||||
|
def __del__(self) -> None:
|
||||||
|
if not self._closed:
|
||||||
|
warnings.warn(
|
||||||
|
f"Unclosed <{self.__class__.__name__} at {id(self):x}>",
|
||||||
|
ResourceWarning,
|
||||||
|
stacklevel=1,
|
||||||
|
source=self,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class MemoryObjectSendStream(ObjectSendStream[T_contra], Generic[T_contra]):
|
||||||
|
_state: _MemoryObjectStreamState[T_contra]
|
||||||
|
_closed: bool = field(init=False, default=False)
|
||||||
|
|
||||||
|
def __post_init__(self) -> None:
|
||||||
|
self._state.open_send_channels += 1
|
||||||
|
|
||||||
|
def send_nowait(self, item: T_contra) -> None:
|
||||||
|
"""
|
||||||
|
Send an item immediately if it can be done without waiting.
|
||||||
|
|
||||||
|
:param item: the item to send
|
||||||
|
:raises ~anyio.ClosedResourceError: if this send stream has been closed
|
||||||
|
:raises ~anyio.BrokenResourceError: if the stream has been closed from the
|
||||||
|
receiving end
|
||||||
|
:raises ~anyio.WouldBlock: if the buffer is full and there are no tasks waiting
|
||||||
|
to receive
|
||||||
|
|
||||||
|
"""
|
||||||
|
if self._closed:
|
||||||
|
raise ClosedResourceError
|
||||||
|
if not self._state.open_receive_channels:
|
||||||
|
raise BrokenResourceError
|
||||||
|
|
||||||
|
while self._state.waiting_receivers:
|
||||||
|
receive_event, receiver = self._state.waiting_receivers.popitem(last=False)
|
||||||
|
if not receiver.task_info.has_pending_cancellation():
|
||||||
|
receiver.item = item
|
||||||
|
receive_event.set()
|
||||||
|
return
|
||||||
|
|
||||||
|
if len(self._state.buffer) < self._state.max_buffer_size:
|
||||||
|
self._state.buffer.append(item)
|
||||||
|
else:
|
||||||
|
raise WouldBlock
|
||||||
|
|
||||||
|
async def send(self, item: T_contra) -> None:
|
||||||
|
"""
|
||||||
|
Send an item to the stream.
|
||||||
|
|
||||||
|
If the buffer is full, this method blocks until there is again room in the
|
||||||
|
buffer or the item can be sent directly to a receiver.
|
||||||
|
|
||||||
|
:param item: the item to send
|
||||||
|
:raises ~anyio.ClosedResourceError: if this send stream has been closed
|
||||||
|
:raises ~anyio.BrokenResourceError: if the stream has been closed from the
|
||||||
|
receiving end
|
||||||
|
|
||||||
|
"""
|
||||||
|
await checkpoint()
|
||||||
|
try:
|
||||||
|
self.send_nowait(item)
|
||||||
|
except WouldBlock:
|
||||||
|
# Wait until there's someone on the receiving end
|
||||||
|
send_event = Event()
|
||||||
|
self._state.waiting_senders[send_event] = item
|
||||||
|
try:
|
||||||
|
await send_event.wait()
|
||||||
|
except BaseException:
|
||||||
|
self._state.waiting_senders.pop(send_event, None)
|
||||||
|
raise
|
||||||
|
|
||||||
|
if send_event in self._state.waiting_senders:
|
||||||
|
del self._state.waiting_senders[send_event]
|
||||||
|
raise BrokenResourceError from None
|
||||||
|
|
||||||
|
def clone(self) -> MemoryObjectSendStream[T_contra]:
|
||||||
|
"""
|
||||||
|
Create a clone of this send stream.
|
||||||
|
|
||||||
|
Each clone can be closed separately. Only when all clones have been closed will
|
||||||
|
the sending end of the memory stream be considered closed by the receiving ends.
|
||||||
|
|
||||||
|
:return: the cloned stream
|
||||||
|
|
||||||
|
"""
|
||||||
|
if self._closed:
|
||||||
|
raise ClosedResourceError
|
||||||
|
|
||||||
|
return MemoryObjectSendStream(_state=self._state)
|
||||||
|
|
||||||
|
def close(self) -> None:
|
||||||
|
"""
|
||||||
|
Close the stream.
|
||||||
|
|
||||||
|
This works the exact same way as :meth:`aclose`, but is provided as a special
|
||||||
|
case for the benefit of synchronous callbacks.
|
||||||
|
|
||||||
|
"""
|
||||||
|
if not self._closed:
|
||||||
|
self._closed = True
|
||||||
|
self._state.open_send_channels -= 1
|
||||||
|
if self._state.open_send_channels == 0:
|
||||||
|
receive_events = list(self._state.waiting_receivers.keys())
|
||||||
|
self._state.waiting_receivers.clear()
|
||||||
|
for event in receive_events:
|
||||||
|
event.set()
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
self.close()
|
||||||
|
|
||||||
|
def statistics(self) -> MemoryObjectStreamStatistics:
|
||||||
|
"""
|
||||||
|
Return statistics about the current state of this stream.
|
||||||
|
|
||||||
|
.. versionadded:: 3.0
|
||||||
|
"""
|
||||||
|
return self._state.statistics()
|
||||||
|
|
||||||
|
def __enter__(self) -> MemoryObjectSendStream[T_contra]:
|
||||||
|
return self
|
||||||
|
|
||||||
|
def __exit__(
|
||||||
|
self,
|
||||||
|
exc_type: type[BaseException] | None,
|
||||||
|
exc_val: BaseException | None,
|
||||||
|
exc_tb: TracebackType | None,
|
||||||
|
) -> None:
|
||||||
|
self.close()
|
||||||
|
|
||||||
|
def __del__(self) -> None:
|
||||||
|
if not self._closed:
|
||||||
|
warnings.warn(
|
||||||
|
f"Unclosed <{self.__class__.__name__} at {id(self):x}>",
|
||||||
|
ResourceWarning,
|
||||||
|
stacklevel=1,
|
||||||
|
source=self,
|
||||||
|
)
|
||||||
@@ -0,0 +1,160 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"MultiListener",
|
||||||
|
"StapledByteStream",
|
||||||
|
"StapledObjectStream",
|
||||||
|
)
|
||||||
|
|
||||||
|
from collections.abc import Callable, Mapping, Sequence
|
||||||
|
from dataclasses import dataclass
|
||||||
|
from typing import Any, Generic, TypeVar
|
||||||
|
|
||||||
|
from ..abc import (
|
||||||
|
ByteReceiveStream,
|
||||||
|
ByteSendStream,
|
||||||
|
ByteStream,
|
||||||
|
Listener,
|
||||||
|
ObjectReceiveStream,
|
||||||
|
ObjectSendStream,
|
||||||
|
ObjectStream,
|
||||||
|
TaskGroup,
|
||||||
|
)
|
||||||
|
|
||||||
|
T_Item = TypeVar("T_Item")
|
||||||
|
T_Stream = TypeVar("T_Stream")
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class StapledByteStream(ByteStream):
|
||||||
|
"""
|
||||||
|
Combines two byte streams into a single, bidirectional byte stream.
|
||||||
|
|
||||||
|
Extra attributes will be provided from both streams, with the receive stream
|
||||||
|
providing the values in case of a conflict.
|
||||||
|
|
||||||
|
:param ByteSendStream send_stream: the sending byte stream
|
||||||
|
:param ByteReceiveStream receive_stream: the receiving byte stream
|
||||||
|
"""
|
||||||
|
|
||||||
|
send_stream: ByteSendStream
|
||||||
|
receive_stream: ByteReceiveStream
|
||||||
|
|
||||||
|
async def receive(self, max_bytes: int = 65536) -> bytes:
|
||||||
|
if max_bytes < 1:
|
||||||
|
raise ValueError("max_bytes must be a positive integer")
|
||||||
|
|
||||||
|
return await self.receive_stream.receive(max_bytes)
|
||||||
|
|
||||||
|
async def send(self, item: bytes) -> None:
|
||||||
|
await self.send_stream.send(item)
|
||||||
|
|
||||||
|
async def send_eof(self) -> None:
|
||||||
|
await self.send_stream.aclose()
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
await self.send_stream.aclose()
|
||||||
|
await self.receive_stream.aclose()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def extra_attributes(self) -> Mapping[Any, Callable[[], Any]]:
|
||||||
|
return {
|
||||||
|
**self.send_stream.extra_attributes,
|
||||||
|
**self.receive_stream.extra_attributes,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class StapledObjectStream(ObjectStream[T_Item], Generic[T_Item]):
|
||||||
|
"""
|
||||||
|
Combines two object streams into a single, bidirectional object stream.
|
||||||
|
|
||||||
|
Extra attributes will be provided from both streams, with the receive stream
|
||||||
|
providing the values in case of a conflict.
|
||||||
|
|
||||||
|
:param ObjectSendStream send_stream: the sending object stream
|
||||||
|
:param ObjectReceiveStream receive_stream: the receiving object stream
|
||||||
|
"""
|
||||||
|
|
||||||
|
send_stream: ObjectSendStream[T_Item]
|
||||||
|
receive_stream: ObjectReceiveStream[T_Item]
|
||||||
|
|
||||||
|
async def receive(self) -> T_Item:
|
||||||
|
return await self.receive_stream.receive()
|
||||||
|
|
||||||
|
async def send(self, item: T_Item) -> None:
|
||||||
|
await self.send_stream.send(item)
|
||||||
|
|
||||||
|
def send_nowait(self, item: T_Item) -> None:
|
||||||
|
try:
|
||||||
|
send_nowait = self.send_stream.send_nowait # type: ignore[attr-defined]
|
||||||
|
except AttributeError as exc:
|
||||||
|
raise NotImplementedError(
|
||||||
|
f"'send_nowait' method not implemented in {type(self.send_stream)}"
|
||||||
|
) from exc
|
||||||
|
|
||||||
|
send_nowait(item)
|
||||||
|
|
||||||
|
async def send_eof(self) -> None:
|
||||||
|
await self.send_stream.aclose()
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
await self.send_stream.aclose()
|
||||||
|
await self.receive_stream.aclose()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def extra_attributes(self) -> Mapping[Any, Callable[[], Any]]:
|
||||||
|
return {
|
||||||
|
**self.send_stream.extra_attributes,
|
||||||
|
**self.receive_stream.extra_attributes,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class MultiListener(Listener[T_Stream], Generic[T_Stream]):
|
||||||
|
"""
|
||||||
|
Combines multiple listeners into one, serving connections from all of them at once.
|
||||||
|
|
||||||
|
Any MultiListeners in the given collection of listeners will have their listeners
|
||||||
|
moved into this one.
|
||||||
|
|
||||||
|
Extra attributes are provided from each listener, with each successive listener
|
||||||
|
overriding any conflicting attributes from the previous one.
|
||||||
|
|
||||||
|
:param listeners: listeners to serve
|
||||||
|
:type listeners: Sequence[Listener[T_Stream]]
|
||||||
|
"""
|
||||||
|
|
||||||
|
listeners: Sequence[Listener[T_Stream]]
|
||||||
|
|
||||||
|
def __post_init__(self) -> None:
|
||||||
|
listeners: list[Listener[T_Stream]] = []
|
||||||
|
for listener in self.listeners:
|
||||||
|
if isinstance(listener, MultiListener):
|
||||||
|
listeners.extend(listener.listeners)
|
||||||
|
del listener.listeners[:] # type: ignore[attr-defined]
|
||||||
|
else:
|
||||||
|
listeners.append(listener)
|
||||||
|
|
||||||
|
self.listeners = listeners
|
||||||
|
|
||||||
|
async def serve(
|
||||||
|
self, handler: Callable[[T_Stream], Any], task_group: TaskGroup | None = None
|
||||||
|
) -> None:
|
||||||
|
from .. import create_task_group
|
||||||
|
|
||||||
|
async with create_task_group() as tg:
|
||||||
|
for listener in self.listeners:
|
||||||
|
tg.start_soon(listener.serve, handler, task_group)
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
for listener in self.listeners:
|
||||||
|
await listener.aclose()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def extra_attributes(self) -> Mapping[Any, Callable[[], Any]]:
|
||||||
|
attributes: dict = {}
|
||||||
|
for listener in self.listeners:
|
||||||
|
attributes.update(listener.extra_attributes)
|
||||||
|
|
||||||
|
return attributes
|
||||||
@@ -0,0 +1,176 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"TextConnectable",
|
||||||
|
"TextReceiveStream",
|
||||||
|
"TextSendStream",
|
||||||
|
"TextStream",
|
||||||
|
)
|
||||||
|
|
||||||
|
import codecs
|
||||||
|
import sys
|
||||||
|
from collections.abc import Callable, Mapping
|
||||||
|
from dataclasses import InitVar, dataclass, field
|
||||||
|
from typing import Any
|
||||||
|
|
||||||
|
from ..abc import (
|
||||||
|
AnyByteReceiveStream,
|
||||||
|
AnyByteSendStream,
|
||||||
|
AnyByteStream,
|
||||||
|
AnyByteStreamConnectable,
|
||||||
|
ObjectReceiveStream,
|
||||||
|
ObjectSendStream,
|
||||||
|
ObjectStream,
|
||||||
|
ObjectStreamConnectable,
|
||||||
|
)
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 12):
|
||||||
|
from typing import override
|
||||||
|
else:
|
||||||
|
from typing_extensions import override
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class TextReceiveStream(ObjectReceiveStream[str]):
|
||||||
|
"""
|
||||||
|
Stream wrapper that decodes bytes to strings using the given encoding.
|
||||||
|
|
||||||
|
Decoding is done using :class:`~codecs.IncrementalDecoder` which returns any
|
||||||
|
completely received unicode characters as soon as they come in.
|
||||||
|
|
||||||
|
:param transport_stream: any bytes-based receive stream
|
||||||
|
:param encoding: character encoding to use for decoding bytes to strings (defaults
|
||||||
|
to ``utf-8``)
|
||||||
|
:param errors: handling scheme for decoding errors (defaults to ``strict``; see the
|
||||||
|
`codecs module documentation`_ for a comprehensive list of options)
|
||||||
|
|
||||||
|
.. _codecs module documentation:
|
||||||
|
https://docs.python.org/3/library/codecs.html#codec-objects
|
||||||
|
"""
|
||||||
|
|
||||||
|
transport_stream: AnyByteReceiveStream
|
||||||
|
encoding: InitVar[str] = "utf-8"
|
||||||
|
errors: InitVar[str] = "strict"
|
||||||
|
_decoder: codecs.IncrementalDecoder = field(init=False)
|
||||||
|
|
||||||
|
def __post_init__(self, encoding: str, errors: str) -> None:
|
||||||
|
decoder_class = codecs.getincrementaldecoder(encoding)
|
||||||
|
self._decoder = decoder_class(errors=errors)
|
||||||
|
|
||||||
|
async def receive(self) -> str:
|
||||||
|
while True:
|
||||||
|
chunk = await self.transport_stream.receive()
|
||||||
|
decoded = self._decoder.decode(chunk)
|
||||||
|
if decoded:
|
||||||
|
return decoded
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
await self.transport_stream.aclose()
|
||||||
|
self._decoder.reset()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def extra_attributes(self) -> Mapping[Any, Callable[[], Any]]:
|
||||||
|
return self.transport_stream.extra_attributes
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class TextSendStream(ObjectSendStream[str]):
|
||||||
|
"""
|
||||||
|
Sends strings to the wrapped stream as bytes using the given encoding.
|
||||||
|
|
||||||
|
:param AnyByteSendStream transport_stream: any bytes-based send stream
|
||||||
|
:param str encoding: character encoding to use for encoding strings to bytes
|
||||||
|
(defaults to ``utf-8``)
|
||||||
|
:param str errors: handling scheme for encoding errors (defaults to ``strict``; see
|
||||||
|
the `codecs module documentation`_ for a comprehensive list of options)
|
||||||
|
|
||||||
|
.. _codecs module documentation:
|
||||||
|
https://docs.python.org/3/library/codecs.html#codec-objects
|
||||||
|
"""
|
||||||
|
|
||||||
|
transport_stream: AnyByteSendStream
|
||||||
|
encoding: InitVar[str] = "utf-8"
|
||||||
|
errors: str = "strict"
|
||||||
|
_encoder: Callable[..., tuple[bytes, int]] = field(init=False)
|
||||||
|
|
||||||
|
def __post_init__(self, encoding: str) -> None:
|
||||||
|
self._encoder = codecs.getencoder(encoding)
|
||||||
|
|
||||||
|
async def send(self, item: str) -> None:
|
||||||
|
encoded = self._encoder(item, self.errors)[0]
|
||||||
|
await self.transport_stream.send(encoded)
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
await self.transport_stream.aclose()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def extra_attributes(self) -> Mapping[Any, Callable[[], Any]]:
|
||||||
|
return self.transport_stream.extra_attributes
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class TextStream(ObjectStream[str]):
|
||||||
|
"""
|
||||||
|
A bidirectional stream that decodes bytes to strings on receive and encodes strings
|
||||||
|
to bytes on send.
|
||||||
|
|
||||||
|
Extra attributes will be provided from both streams, with the receive stream
|
||||||
|
providing the values in case of a conflict.
|
||||||
|
|
||||||
|
:param AnyByteStream transport_stream: any bytes-based stream
|
||||||
|
:param str encoding: character encoding to use for encoding/decoding strings to/from
|
||||||
|
bytes (defaults to ``utf-8``)
|
||||||
|
:param str errors: handling scheme for encoding errors (defaults to ``strict``; see
|
||||||
|
the `codecs module documentation`_ for a comprehensive list of options)
|
||||||
|
|
||||||
|
.. _codecs module documentation:
|
||||||
|
https://docs.python.org/3/library/codecs.html#codec-objects
|
||||||
|
"""
|
||||||
|
|
||||||
|
transport_stream: AnyByteStream
|
||||||
|
encoding: InitVar[str] = "utf-8"
|
||||||
|
errors: InitVar[str] = "strict"
|
||||||
|
_receive_stream: TextReceiveStream = field(init=False)
|
||||||
|
_send_stream: TextSendStream = field(init=False)
|
||||||
|
|
||||||
|
def __post_init__(self, encoding: str, errors: str) -> None:
|
||||||
|
self._receive_stream = TextReceiveStream(
|
||||||
|
self.transport_stream, encoding=encoding, errors=errors
|
||||||
|
)
|
||||||
|
self._send_stream = TextSendStream(
|
||||||
|
self.transport_stream, encoding=encoding, errors=errors
|
||||||
|
)
|
||||||
|
|
||||||
|
async def receive(self) -> str:
|
||||||
|
return await self._receive_stream.receive()
|
||||||
|
|
||||||
|
async def send(self, item: str) -> None:
|
||||||
|
await self._send_stream.send(item)
|
||||||
|
|
||||||
|
async def send_eof(self) -> None:
|
||||||
|
await self.transport_stream.send_eof()
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
await self._send_stream.aclose()
|
||||||
|
await self._receive_stream.aclose()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def extra_attributes(self) -> Mapping[Any, Callable[[], Any]]:
|
||||||
|
return {
|
||||||
|
**self._send_stream.extra_attributes,
|
||||||
|
**self._receive_stream.extra_attributes,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
class TextConnectable(ObjectStreamConnectable[str]):
|
||||||
|
def __init__(self, connectable: AnyByteStreamConnectable):
|
||||||
|
"""
|
||||||
|
:param connectable: the bytestream endpoint to wrap
|
||||||
|
|
||||||
|
"""
|
||||||
|
self.connectable = connectable
|
||||||
|
|
||||||
|
@override
|
||||||
|
async def connect(self) -> TextStream:
|
||||||
|
stream = await self.connectable.connect()
|
||||||
|
return TextStream(stream)
|
||||||
@@ -0,0 +1,436 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"TLSAttribute",
|
||||||
|
"TLSConnectable",
|
||||||
|
"TLSListener",
|
||||||
|
"TLSStream",
|
||||||
|
)
|
||||||
|
|
||||||
|
import logging
|
||||||
|
import re
|
||||||
|
import ssl
|
||||||
|
import sys
|
||||||
|
from collections.abc import Callable, Mapping
|
||||||
|
from dataclasses import dataclass
|
||||||
|
from functools import wraps
|
||||||
|
from ssl import SSLContext
|
||||||
|
from typing import Any, TypeAlias, TypeVar
|
||||||
|
|
||||||
|
from .. import (
|
||||||
|
BrokenResourceError,
|
||||||
|
EndOfStream,
|
||||||
|
aclose_forcefully,
|
||||||
|
get_cancelled_exc_class,
|
||||||
|
to_thread,
|
||||||
|
)
|
||||||
|
from .._core._typedattr import TypedAttributeSet, typed_attribute
|
||||||
|
from ..abc import (
|
||||||
|
AnyByteStream,
|
||||||
|
AnyByteStreamConnectable,
|
||||||
|
ByteStream,
|
||||||
|
ByteStreamConnectable,
|
||||||
|
Listener,
|
||||||
|
TaskGroup,
|
||||||
|
)
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import TypeVarTuple, Unpack
|
||||||
|
else:
|
||||||
|
from typing_extensions import TypeVarTuple, Unpack
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 12):
|
||||||
|
from typing import override
|
||||||
|
else:
|
||||||
|
from typing_extensions import override
|
||||||
|
|
||||||
|
T_Retval = TypeVar("T_Retval")
|
||||||
|
PosArgsT = TypeVarTuple("PosArgsT")
|
||||||
|
_PCTRTT: TypeAlias = tuple[tuple[str, str], ...]
|
||||||
|
_PCTRTTT: TypeAlias = tuple[_PCTRTT, ...]
|
||||||
|
|
||||||
|
|
||||||
|
class TLSAttribute(TypedAttributeSet):
|
||||||
|
"""Contains Transport Layer Security related attributes."""
|
||||||
|
|
||||||
|
#: the selected ALPN protocol
|
||||||
|
alpn_protocol: str | None = typed_attribute()
|
||||||
|
#: the channel binding for type ``tls-unique``
|
||||||
|
channel_binding_tls_unique: bytes = typed_attribute()
|
||||||
|
#: the selected cipher
|
||||||
|
cipher: tuple[str, str, int] = typed_attribute()
|
||||||
|
#: the peer certificate in dictionary form (see :meth:`ssl.SSLSocket.getpeercert`
|
||||||
|
# for more information)
|
||||||
|
peer_certificate: None | (dict[str, str | _PCTRTTT | _PCTRTT]) = typed_attribute()
|
||||||
|
#: the peer certificate in binary form
|
||||||
|
peer_certificate_binary: bytes | None = typed_attribute()
|
||||||
|
#: ``True`` if this is the server side of the connection
|
||||||
|
server_side: bool = typed_attribute()
|
||||||
|
#: ciphers shared by the client during the TLS handshake (``None`` if this is the
|
||||||
|
#: client side)
|
||||||
|
shared_ciphers: list[tuple[str, str, int]] | None = typed_attribute()
|
||||||
|
#: the :class:`~ssl.SSLObject` used for encryption
|
||||||
|
ssl_object: ssl.SSLObject = typed_attribute()
|
||||||
|
#: ``True`` if this stream does (and expects) a closing TLS handshake when the
|
||||||
|
#: stream is being closed
|
||||||
|
standard_compatible: bool = typed_attribute()
|
||||||
|
#: the TLS protocol version (e.g. ``TLSv1.2``)
|
||||||
|
tls_version: str = typed_attribute()
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class TLSStream(ByteStream):
|
||||||
|
"""
|
||||||
|
A stream wrapper that encrypts all sent data and decrypts received data.
|
||||||
|
|
||||||
|
This class has no public initializer; use :meth:`wrap` instead.
|
||||||
|
All extra attributes from :class:`~TLSAttribute` are supported.
|
||||||
|
|
||||||
|
:var AnyByteStream transport_stream: the wrapped stream
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
transport_stream: AnyByteStream
|
||||||
|
standard_compatible: bool
|
||||||
|
_ssl_object: ssl.SSLObject
|
||||||
|
_read_bio: ssl.MemoryBIO
|
||||||
|
_write_bio: ssl.MemoryBIO
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
async def wrap(
|
||||||
|
cls,
|
||||||
|
transport_stream: AnyByteStream,
|
||||||
|
*,
|
||||||
|
server_side: bool | None = None,
|
||||||
|
hostname: str | None = None,
|
||||||
|
ssl_context: ssl.SSLContext | None = None,
|
||||||
|
standard_compatible: bool = True,
|
||||||
|
) -> TLSStream:
|
||||||
|
"""
|
||||||
|
Wrap an existing stream with Transport Layer Security.
|
||||||
|
|
||||||
|
This performs a TLS handshake with the peer.
|
||||||
|
|
||||||
|
:param transport_stream: a bytes-transporting stream to wrap
|
||||||
|
:param server_side: ``True`` if this is the server side of the connection,
|
||||||
|
``False`` if this is the client side (if omitted, will be set to ``False``
|
||||||
|
if ``hostname`` has been provided, ``False`` otherwise). Used only to create
|
||||||
|
a default context when an explicit context has not been provided.
|
||||||
|
:param hostname: host name of the peer (if host name checking is desired)
|
||||||
|
:param ssl_context: the SSLContext object to use (if not provided, a secure
|
||||||
|
default will be created)
|
||||||
|
:param standard_compatible: if ``False``, skip the closing handshake when
|
||||||
|
closing the connection, and don't raise an exception if the peer does the
|
||||||
|
same
|
||||||
|
:raises ~ssl.SSLError: if the TLS handshake fails
|
||||||
|
|
||||||
|
"""
|
||||||
|
if server_side is None:
|
||||||
|
server_side = not hostname
|
||||||
|
|
||||||
|
if not ssl_context:
|
||||||
|
purpose = (
|
||||||
|
ssl.Purpose.CLIENT_AUTH if server_side else ssl.Purpose.SERVER_AUTH
|
||||||
|
)
|
||||||
|
ssl_context = ssl.create_default_context(purpose)
|
||||||
|
|
||||||
|
# Re-enable detection of unexpected EOFs if it was disabled by Python
|
||||||
|
if hasattr(ssl, "OP_IGNORE_UNEXPECTED_EOF"):
|
||||||
|
ssl_context.options &= ~ssl.OP_IGNORE_UNEXPECTED_EOF
|
||||||
|
|
||||||
|
bio_in = ssl.MemoryBIO()
|
||||||
|
bio_out = ssl.MemoryBIO()
|
||||||
|
|
||||||
|
# Resolve international host names using IDNA 2008.
|
||||||
|
# Otherwise wrap_bio() would resolve them with IDNA 2003.
|
||||||
|
if hostname is not None:
|
||||||
|
from .._core._sockets import idna2008_resolve
|
||||||
|
|
||||||
|
server_hostname: bytes | None = idna2008_resolve(hostname)
|
||||||
|
else:
|
||||||
|
server_hostname = None
|
||||||
|
|
||||||
|
# External SSLContext implementations may do blocking I/O in wrap_bio(),
|
||||||
|
# but the standard library implementation won't
|
||||||
|
if type(ssl_context) is ssl.SSLContext:
|
||||||
|
ssl_object = ssl_context.wrap_bio(
|
||||||
|
bio_in,
|
||||||
|
bio_out,
|
||||||
|
server_side=server_side,
|
||||||
|
server_hostname=server_hostname,
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
ssl_object = await to_thread.run_sync(
|
||||||
|
ssl_context.wrap_bio,
|
||||||
|
bio_in,
|
||||||
|
bio_out,
|
||||||
|
server_side,
|
||||||
|
server_hostname,
|
||||||
|
None,
|
||||||
|
)
|
||||||
|
|
||||||
|
wrapper = cls(
|
||||||
|
transport_stream=transport_stream,
|
||||||
|
standard_compatible=standard_compatible,
|
||||||
|
_ssl_object=ssl_object,
|
||||||
|
_read_bio=bio_in,
|
||||||
|
_write_bio=bio_out,
|
||||||
|
)
|
||||||
|
await wrapper._call_sslobject_method(ssl_object.do_handshake)
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
async def _call_sslobject_method(
|
||||||
|
self, func: Callable[[Unpack[PosArgsT]], T_Retval], *args: Unpack[PosArgsT]
|
||||||
|
) -> T_Retval:
|
||||||
|
while True:
|
||||||
|
try:
|
||||||
|
result = func(*args)
|
||||||
|
except ssl.SSLWantReadError:
|
||||||
|
try:
|
||||||
|
# Flush any pending writes first
|
||||||
|
if self._write_bio.pending:
|
||||||
|
await self.transport_stream.send(self._write_bio.read())
|
||||||
|
|
||||||
|
data = await self.transport_stream.receive()
|
||||||
|
except EndOfStream:
|
||||||
|
self._read_bio.write_eof()
|
||||||
|
except OSError as exc:
|
||||||
|
self._read_bio.write_eof()
|
||||||
|
self._write_bio.write_eof()
|
||||||
|
raise BrokenResourceError from exc
|
||||||
|
else:
|
||||||
|
self._read_bio.write(data)
|
||||||
|
except ssl.SSLWantWriteError:
|
||||||
|
await self.transport_stream.send(self._write_bio.read())
|
||||||
|
except ssl.SSLSyscallError as exc:
|
||||||
|
self._read_bio.write_eof()
|
||||||
|
self._write_bio.write_eof()
|
||||||
|
raise BrokenResourceError from exc
|
||||||
|
except ssl.SSLError as exc:
|
||||||
|
self._read_bio.write_eof()
|
||||||
|
self._write_bio.write_eof()
|
||||||
|
if isinstance(exc, ssl.SSLEOFError) or (
|
||||||
|
exc.strerror and "UNEXPECTED_EOF_WHILE_READING" in exc.strerror
|
||||||
|
):
|
||||||
|
if self.standard_compatible:
|
||||||
|
raise BrokenResourceError from exc
|
||||||
|
else:
|
||||||
|
raise EndOfStream from None
|
||||||
|
|
||||||
|
raise
|
||||||
|
else:
|
||||||
|
# Flush any pending writes first
|
||||||
|
if self._write_bio.pending:
|
||||||
|
await self.transport_stream.send(self._write_bio.read())
|
||||||
|
|
||||||
|
return result
|
||||||
|
|
||||||
|
async def unwrap(self) -> tuple[AnyByteStream, bytes]:
|
||||||
|
"""
|
||||||
|
Does the TLS closing handshake.
|
||||||
|
|
||||||
|
:return: a tuple of (wrapped byte stream, bytes left in the read buffer)
|
||||||
|
|
||||||
|
"""
|
||||||
|
await self._call_sslobject_method(self._ssl_object.unwrap)
|
||||||
|
self._read_bio.write_eof()
|
||||||
|
self._write_bio.write_eof()
|
||||||
|
return self.transport_stream, self._read_bio.read()
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
if self.standard_compatible:
|
||||||
|
try:
|
||||||
|
await self.unwrap()
|
||||||
|
except BaseException:
|
||||||
|
await aclose_forcefully(self.transport_stream)
|
||||||
|
raise
|
||||||
|
|
||||||
|
await self.transport_stream.aclose()
|
||||||
|
|
||||||
|
async def receive(self, max_bytes: int = 65536) -> bytes:
|
||||||
|
if max_bytes < 1:
|
||||||
|
raise ValueError("max_bytes must be a positive integer")
|
||||||
|
|
||||||
|
data = await self._call_sslobject_method(self._ssl_object.read, max_bytes)
|
||||||
|
if not data:
|
||||||
|
raise EndOfStream
|
||||||
|
|
||||||
|
return data
|
||||||
|
|
||||||
|
async def send(self, item: bytes) -> None:
|
||||||
|
await self._call_sslobject_method(self._ssl_object.write, item)
|
||||||
|
|
||||||
|
async def send_eof(self) -> None:
|
||||||
|
tls_version = self.extra(TLSAttribute.tls_version)
|
||||||
|
match = re.match(r"TLSv(\d+)(?:\.(\d+))?", tls_version)
|
||||||
|
if match:
|
||||||
|
major, minor = int(match.group(1)), int(match.group(2) or 0)
|
||||||
|
if (major, minor) < (1, 3):
|
||||||
|
raise NotImplementedError(
|
||||||
|
f"send_eof() requires at least TLSv1.3; current "
|
||||||
|
f"session uses {tls_version}"
|
||||||
|
)
|
||||||
|
|
||||||
|
raise NotImplementedError(
|
||||||
|
"send_eof() has not yet been implemented for TLS streams"
|
||||||
|
)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def extra_attributes(self) -> Mapping[Any, Callable[[], Any]]:
|
||||||
|
return {
|
||||||
|
**self.transport_stream.extra_attributes,
|
||||||
|
TLSAttribute.alpn_protocol: self._ssl_object.selected_alpn_protocol,
|
||||||
|
TLSAttribute.channel_binding_tls_unique: (
|
||||||
|
self._ssl_object.get_channel_binding
|
||||||
|
),
|
||||||
|
TLSAttribute.cipher: self._ssl_object.cipher,
|
||||||
|
TLSAttribute.peer_certificate: lambda: self._ssl_object.getpeercert(False),
|
||||||
|
TLSAttribute.peer_certificate_binary: lambda: self._ssl_object.getpeercert(
|
||||||
|
True
|
||||||
|
),
|
||||||
|
TLSAttribute.server_side: lambda: self._ssl_object.server_side,
|
||||||
|
TLSAttribute.shared_ciphers: lambda: (
|
||||||
|
self._ssl_object.shared_ciphers()
|
||||||
|
if self._ssl_object.server_side
|
||||||
|
else None
|
||||||
|
),
|
||||||
|
TLSAttribute.standard_compatible: lambda: self.standard_compatible,
|
||||||
|
TLSAttribute.ssl_object: lambda: self._ssl_object,
|
||||||
|
TLSAttribute.tls_version: self._ssl_object.version,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(eq=False)
|
||||||
|
class TLSListener(Listener[TLSStream]):
|
||||||
|
"""
|
||||||
|
A convenience listener that wraps another listener and auto-negotiates a TLS session
|
||||||
|
on every accepted connection.
|
||||||
|
|
||||||
|
If the TLS handshake times out or raises an exception,
|
||||||
|
:meth:`handle_handshake_error` is called to do whatever post-mortem processing is
|
||||||
|
deemed necessary.
|
||||||
|
|
||||||
|
Supports only the :attr:`~TLSAttribute.standard_compatible` extra attribute.
|
||||||
|
|
||||||
|
:param Listener listener: the listener to wrap
|
||||||
|
:param ssl_context: the SSL context object
|
||||||
|
:param standard_compatible: a flag passed through to :meth:`TLSStream.wrap`
|
||||||
|
:param handshake_timeout: time limit for the TLS handshake
|
||||||
|
(passed to :func:`~anyio.fail_after`)
|
||||||
|
"""
|
||||||
|
|
||||||
|
listener: Listener[Any]
|
||||||
|
ssl_context: ssl.SSLContext
|
||||||
|
standard_compatible: bool = True
|
||||||
|
handshake_timeout: float = 30
|
||||||
|
|
||||||
|
@staticmethod
|
||||||
|
async def handle_handshake_error(exc: BaseException, stream: AnyByteStream) -> None:
|
||||||
|
"""
|
||||||
|
Handle an exception raised during the TLS handshake.
|
||||||
|
|
||||||
|
This method does 3 things:
|
||||||
|
|
||||||
|
#. Forcefully closes the original stream
|
||||||
|
#. Logs the exception (unless it was a cancellation exception) using the
|
||||||
|
``anyio.streams.tls`` logger
|
||||||
|
#. Reraises the exception if it was a base exception or a cancellation exception
|
||||||
|
|
||||||
|
:param exc: the exception
|
||||||
|
:param stream: the original stream
|
||||||
|
|
||||||
|
"""
|
||||||
|
await aclose_forcefully(stream)
|
||||||
|
|
||||||
|
# Log all except cancellation exceptions
|
||||||
|
if not isinstance(exc, get_cancelled_exc_class()):
|
||||||
|
# CPython (as of 3.11.5) returns incorrect `sys.exc_info()` here when using
|
||||||
|
# any asyncio implementation, so we explicitly pass the exception to log
|
||||||
|
# (https://github.com/python/cpython/issues/108668). Trio does not have this
|
||||||
|
# issue because it works around the CPython bug.
|
||||||
|
logging.getLogger(__name__).exception(
|
||||||
|
"Error during TLS handshake", exc_info=exc
|
||||||
|
)
|
||||||
|
|
||||||
|
# Only reraise base exceptions and cancellation exceptions
|
||||||
|
if not isinstance(exc, Exception) or isinstance(exc, get_cancelled_exc_class()):
|
||||||
|
raise # noqa: PLE0704
|
||||||
|
|
||||||
|
async def serve(
|
||||||
|
self,
|
||||||
|
handler: Callable[[TLSStream], Any],
|
||||||
|
task_group: TaskGroup | None = None,
|
||||||
|
) -> None:
|
||||||
|
@wraps(handler)
|
||||||
|
async def handler_wrapper(stream: AnyByteStream) -> None:
|
||||||
|
from .. import fail_after
|
||||||
|
|
||||||
|
try:
|
||||||
|
with fail_after(self.handshake_timeout):
|
||||||
|
wrapped_stream = await TLSStream.wrap(
|
||||||
|
stream,
|
||||||
|
ssl_context=self.ssl_context,
|
||||||
|
standard_compatible=self.standard_compatible,
|
||||||
|
)
|
||||||
|
except BaseException as exc:
|
||||||
|
await self.handle_handshake_error(exc, stream)
|
||||||
|
else:
|
||||||
|
await handler(wrapped_stream)
|
||||||
|
|
||||||
|
await self.listener.serve(handler_wrapper, task_group)
|
||||||
|
|
||||||
|
async def aclose(self) -> None:
|
||||||
|
await self.listener.aclose()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def extra_attributes(self) -> Mapping[Any, Callable[[], Any]]:
|
||||||
|
return {
|
||||||
|
TLSAttribute.standard_compatible: lambda: self.standard_compatible,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
class TLSConnectable(ByteStreamConnectable):
|
||||||
|
"""
|
||||||
|
Wraps another connectable and does TLS negotiation after a successful connection.
|
||||||
|
|
||||||
|
:param connectable: the connectable to wrap
|
||||||
|
:param hostname: host name of the server (if host name checking is desired)
|
||||||
|
:param ssl_context: the SSLContext object to use (if not provided, a secure default
|
||||||
|
will be created)
|
||||||
|
:param standard_compatible: if ``False``, skip the closing handshake when closing
|
||||||
|
the connection, and don't raise an exception if the server does the same
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
connectable: AnyByteStreamConnectable,
|
||||||
|
*,
|
||||||
|
hostname: str | None = None,
|
||||||
|
ssl_context: ssl.SSLContext | None = None,
|
||||||
|
standard_compatible: bool = True,
|
||||||
|
) -> None:
|
||||||
|
self.connectable = connectable
|
||||||
|
self.ssl_context: SSLContext = ssl_context or ssl.create_default_context(
|
||||||
|
ssl.Purpose.SERVER_AUTH
|
||||||
|
)
|
||||||
|
if not isinstance(self.ssl_context, ssl.SSLContext):
|
||||||
|
raise TypeError(
|
||||||
|
"ssl_context must be an instance of ssl.SSLContext, not "
|
||||||
|
f"{type(self.ssl_context).__name__}"
|
||||||
|
)
|
||||||
|
self.hostname = hostname
|
||||||
|
self.standard_compatible = standard_compatible
|
||||||
|
|
||||||
|
@override
|
||||||
|
async def connect(self) -> TLSStream:
|
||||||
|
stream = await self.connectable.connect()
|
||||||
|
try:
|
||||||
|
return await TLSStream.wrap(
|
||||||
|
stream,
|
||||||
|
hostname=self.hostname,
|
||||||
|
ssl_context=self.ssl_context,
|
||||||
|
standard_compatible=self.standard_compatible,
|
||||||
|
)
|
||||||
|
except BaseException:
|
||||||
|
await aclose_forcefully(stream)
|
||||||
|
raise
|
||||||
@@ -0,0 +1,246 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"current_default_interpreter_limiter",
|
||||||
|
"run_sync",
|
||||||
|
)
|
||||||
|
|
||||||
|
import atexit
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
from collections import deque
|
||||||
|
from collections.abc import Callable
|
||||||
|
from typing import Any, Final, TypeVar
|
||||||
|
|
||||||
|
from . import current_time, to_thread
|
||||||
|
from ._core._exceptions import BrokenWorkerInterpreter
|
||||||
|
from ._core._synchronization import CapacityLimiter
|
||||||
|
from .lowlevel import RunVar
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import TypeVarTuple, Unpack
|
||||||
|
else:
|
||||||
|
from typing_extensions import TypeVarTuple, Unpack
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 14):
|
||||||
|
from concurrent.interpreters import ExecutionFailed, create
|
||||||
|
|
||||||
|
def _interp_call(
|
||||||
|
func: Callable[..., Any], args: tuple[Any, ...]
|
||||||
|
) -> tuple[Any, bool]:
|
||||||
|
try:
|
||||||
|
retval = func(*args)
|
||||||
|
except BaseException as exc:
|
||||||
|
return exc, True
|
||||||
|
else:
|
||||||
|
return retval, False
|
||||||
|
|
||||||
|
class _Worker:
|
||||||
|
last_used: float = 0
|
||||||
|
|
||||||
|
def __init__(self) -> None:
|
||||||
|
self._interpreter = create()
|
||||||
|
|
||||||
|
def destroy(self) -> None:
|
||||||
|
self._interpreter.close()
|
||||||
|
|
||||||
|
def call(
|
||||||
|
self,
|
||||||
|
func: Callable[..., T_Retval],
|
||||||
|
args: tuple[Any, ...],
|
||||||
|
) -> T_Retval:
|
||||||
|
try:
|
||||||
|
res, is_exception = self._interpreter.call(_interp_call, func, args)
|
||||||
|
except ExecutionFailed as exc:
|
||||||
|
raise BrokenWorkerInterpreter(exc.excinfo) from exc
|
||||||
|
|
||||||
|
if is_exception:
|
||||||
|
raise res
|
||||||
|
|
||||||
|
return res
|
||||||
|
elif sys.version_info >= (3, 13):
|
||||||
|
import _interpqueues
|
||||||
|
import _interpreters
|
||||||
|
|
||||||
|
UNBOUND: Final = 2 # I have no clue how this works, but it was used in the stdlib
|
||||||
|
FMT_UNPICKLED: Final = 0
|
||||||
|
FMT_PICKLED: Final = 1
|
||||||
|
QUEUE_PICKLE_ARGS: Final = (FMT_PICKLED, UNBOUND)
|
||||||
|
QUEUE_UNPICKLE_ARGS: Final = (FMT_UNPICKLED, UNBOUND)
|
||||||
|
|
||||||
|
_run_func = compile(
|
||||||
|
"""
|
||||||
|
import _interpqueues
|
||||||
|
from _interpreters import NotShareableError
|
||||||
|
from pickle import loads, dumps, HIGHEST_PROTOCOL
|
||||||
|
|
||||||
|
QUEUE_PICKLE_ARGS = (1, 2)
|
||||||
|
QUEUE_UNPICKLE_ARGS = (0, 2)
|
||||||
|
|
||||||
|
item = _interpqueues.get(queue_id)[0]
|
||||||
|
try:
|
||||||
|
func, args = loads(item)
|
||||||
|
retval = func(*args)
|
||||||
|
except BaseException as exc:
|
||||||
|
is_exception = True
|
||||||
|
retval = exc
|
||||||
|
else:
|
||||||
|
is_exception = False
|
||||||
|
|
||||||
|
try:
|
||||||
|
_interpqueues.put(queue_id, (retval, is_exception), *QUEUE_UNPICKLE_ARGS)
|
||||||
|
except NotShareableError:
|
||||||
|
retval = dumps(retval, HIGHEST_PROTOCOL)
|
||||||
|
_interpqueues.put(queue_id, (retval, is_exception), *QUEUE_PICKLE_ARGS)
|
||||||
|
""",
|
||||||
|
"<string>",
|
||||||
|
"exec",
|
||||||
|
)
|
||||||
|
|
||||||
|
class _Worker:
|
||||||
|
last_used: float = 0
|
||||||
|
|
||||||
|
def __init__(self) -> None:
|
||||||
|
self._interpreter_id = _interpreters.create()
|
||||||
|
self._queue_id = _interpqueues.create(1, *QUEUE_UNPICKLE_ARGS)
|
||||||
|
_interpreters.set___main___attrs(
|
||||||
|
self._interpreter_id, {"queue_id": self._queue_id}
|
||||||
|
)
|
||||||
|
|
||||||
|
def destroy(self) -> None:
|
||||||
|
_interpqueues.destroy(self._queue_id)
|
||||||
|
_interpreters.destroy(self._interpreter_id)
|
||||||
|
|
||||||
|
def call(
|
||||||
|
self,
|
||||||
|
func: Callable[..., T_Retval],
|
||||||
|
args: tuple[Any, ...],
|
||||||
|
) -> T_Retval:
|
||||||
|
import pickle
|
||||||
|
|
||||||
|
item = pickle.dumps((func, args), pickle.HIGHEST_PROTOCOL)
|
||||||
|
_interpqueues.put(self._queue_id, item, *QUEUE_PICKLE_ARGS)
|
||||||
|
exc_info = _interpreters.exec(self._interpreter_id, _run_func)
|
||||||
|
if exc_info:
|
||||||
|
raise BrokenWorkerInterpreter(exc_info)
|
||||||
|
|
||||||
|
res = _interpqueues.get(self._queue_id)
|
||||||
|
(res, is_exception), fmt = res[:2]
|
||||||
|
if fmt == FMT_PICKLED:
|
||||||
|
res = pickle.loads(res)
|
||||||
|
|
||||||
|
if is_exception:
|
||||||
|
raise res
|
||||||
|
|
||||||
|
return res
|
||||||
|
else:
|
||||||
|
|
||||||
|
class _Worker:
|
||||||
|
last_used: float = 0
|
||||||
|
|
||||||
|
def __init__(self) -> None:
|
||||||
|
raise RuntimeError("subinterpreters require at least Python 3.13")
|
||||||
|
|
||||||
|
def call(
|
||||||
|
self,
|
||||||
|
func: Callable[..., T_Retval],
|
||||||
|
args: tuple[Any, ...],
|
||||||
|
) -> T_Retval:
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
def destroy(self) -> None:
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
DEFAULT_CPU_COUNT: Final = 8 # this is just an arbitrarily selected value
|
||||||
|
MAX_WORKER_IDLE_TIME = (
|
||||||
|
30 # seconds a subinterpreter can be idle before becoming eligible for pruning
|
||||||
|
)
|
||||||
|
|
||||||
|
T_Retval = TypeVar("T_Retval")
|
||||||
|
PosArgsT = TypeVarTuple("PosArgsT")
|
||||||
|
|
||||||
|
_idle_workers = RunVar[deque[_Worker]]("_available_workers")
|
||||||
|
_default_interpreter_limiter = RunVar[CapacityLimiter]("_default_interpreter_limiter")
|
||||||
|
|
||||||
|
|
||||||
|
def _stop_workers(workers: deque[_Worker]) -> None:
|
||||||
|
for worker in workers:
|
||||||
|
worker.destroy()
|
||||||
|
|
||||||
|
workers.clear()
|
||||||
|
|
||||||
|
|
||||||
|
async def run_sync(
|
||||||
|
func: Callable[[Unpack[PosArgsT]], T_Retval],
|
||||||
|
*args: Unpack[PosArgsT],
|
||||||
|
limiter: CapacityLimiter | None = None,
|
||||||
|
) -> T_Retval:
|
||||||
|
"""
|
||||||
|
Call the given function with the given arguments in a subinterpreter.
|
||||||
|
|
||||||
|
.. warning:: On Python 3.13, the :mod:`concurrent.interpreters` module was not yet
|
||||||
|
available, so the code path for that Python version relies on an undocumented,
|
||||||
|
private API. As such, it is recommended to not rely on this function for anything
|
||||||
|
mission-critical on Python 3.13.
|
||||||
|
|
||||||
|
:param func: a callable
|
||||||
|
:param args: the positional arguments for the callable
|
||||||
|
:param limiter: capacity limiter to use to limit the total number of subinterpreters
|
||||||
|
running (if omitted, the default limiter is used)
|
||||||
|
:return: the result of the call
|
||||||
|
:raises BrokenWorkerInterpreter: if there's an internal error in a subinterpreter
|
||||||
|
|
||||||
|
"""
|
||||||
|
if limiter is None:
|
||||||
|
limiter = current_default_interpreter_limiter()
|
||||||
|
|
||||||
|
try:
|
||||||
|
idle_workers = _idle_workers.get()
|
||||||
|
except LookupError:
|
||||||
|
idle_workers = deque()
|
||||||
|
_idle_workers.set(idle_workers)
|
||||||
|
atexit.register(_stop_workers, idle_workers)
|
||||||
|
|
||||||
|
async with limiter:
|
||||||
|
try:
|
||||||
|
worker = idle_workers.pop()
|
||||||
|
except IndexError:
|
||||||
|
worker = _Worker()
|
||||||
|
|
||||||
|
try:
|
||||||
|
return await to_thread.run_sync(
|
||||||
|
worker.call,
|
||||||
|
func,
|
||||||
|
args,
|
||||||
|
limiter=limiter,
|
||||||
|
)
|
||||||
|
finally:
|
||||||
|
# Prune workers that have been idle for too long
|
||||||
|
now = current_time()
|
||||||
|
while idle_workers:
|
||||||
|
if now - idle_workers[0].last_used <= MAX_WORKER_IDLE_TIME:
|
||||||
|
break
|
||||||
|
|
||||||
|
await to_thread.run_sync(idle_workers.popleft().destroy, limiter=limiter)
|
||||||
|
|
||||||
|
worker.last_used = current_time()
|
||||||
|
idle_workers.append(worker)
|
||||||
|
|
||||||
|
|
||||||
|
def current_default_interpreter_limiter() -> CapacityLimiter:
|
||||||
|
"""
|
||||||
|
Return the capacity limiter used by default to limit the number of concurrently
|
||||||
|
running subinterpreters.
|
||||||
|
|
||||||
|
Defaults to the number of CPU cores.
|
||||||
|
|
||||||
|
:return: a capacity limiter object
|
||||||
|
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
return _default_interpreter_limiter.get()
|
||||||
|
except LookupError:
|
||||||
|
limiter = CapacityLimiter(os.cpu_count() or DEFAULT_CPU_COUNT)
|
||||||
|
_default_interpreter_limiter.set(limiter)
|
||||||
|
return limiter
|
||||||
@@ -0,0 +1,269 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"current_default_process_limiter",
|
||||||
|
"process_worker",
|
||||||
|
"run_sync",
|
||||||
|
)
|
||||||
|
|
||||||
|
import os
|
||||||
|
import pickle
|
||||||
|
import runpy
|
||||||
|
import subprocess
|
||||||
|
import sys
|
||||||
|
from collections import deque
|
||||||
|
from collections.abc import Callable
|
||||||
|
from types import ModuleType
|
||||||
|
from typing import TypeVar, cast
|
||||||
|
|
||||||
|
from ._core._eventloop import current_time, get_async_backend, get_cancelled_exc_class
|
||||||
|
from ._core._exceptions import BrokenWorkerProcess
|
||||||
|
from ._core._subprocesses import open_process
|
||||||
|
from ._core._synchronization import CapacityLimiter
|
||||||
|
from ._core._tasks import CancelScope, fail_after
|
||||||
|
from .abc import ByteReceiveStream, ByteSendStream, Process
|
||||||
|
from .lowlevel import RunVar, checkpoint_if_cancelled
|
||||||
|
from .streams.buffered import BufferedByteReceiveStream
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import TypeVarTuple, Unpack
|
||||||
|
else:
|
||||||
|
from typing_extensions import TypeVarTuple, Unpack
|
||||||
|
|
||||||
|
WORKER_MAX_IDLE_TIME = 300 # 5 minutes
|
||||||
|
|
||||||
|
T_Retval = TypeVar("T_Retval")
|
||||||
|
PosArgsT = TypeVarTuple("PosArgsT")
|
||||||
|
|
||||||
|
_process_pool_workers: RunVar[set[Process]] = RunVar("_process_pool_workers")
|
||||||
|
_process_pool_idle_workers: RunVar[deque[tuple[Process, float]]] = RunVar(
|
||||||
|
"_process_pool_idle_workers"
|
||||||
|
)
|
||||||
|
_default_process_limiter: RunVar[CapacityLimiter] = RunVar("_default_process_limiter")
|
||||||
|
|
||||||
|
|
||||||
|
async def run_sync( # type: ignore[return]
|
||||||
|
func: Callable[[Unpack[PosArgsT]], T_Retval],
|
||||||
|
*args: Unpack[PosArgsT],
|
||||||
|
cancellable: bool = False,
|
||||||
|
limiter: CapacityLimiter | None = None,
|
||||||
|
) -> T_Retval:
|
||||||
|
"""
|
||||||
|
Call the given function with the given arguments in a worker process.
|
||||||
|
|
||||||
|
If the ``cancellable`` option is enabled and the task waiting for its completion is
|
||||||
|
cancelled, the worker process running it will be abruptly terminated using SIGKILL
|
||||||
|
(or ``terminateProcess()`` on Windows).
|
||||||
|
|
||||||
|
:param func: a callable
|
||||||
|
:param args: positional arguments for the callable
|
||||||
|
:param cancellable: ``True`` to allow cancellation of the operation while it's
|
||||||
|
running
|
||||||
|
:param limiter: capacity limiter to use to limit the total amount of processes
|
||||||
|
running (if omitted, the default limiter is used)
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
:return: an awaitable that yields the return value of the function.
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
async def send_raw_command(pickled_cmd: bytes) -> object:
|
||||||
|
try:
|
||||||
|
await stdin.send(pickled_cmd)
|
||||||
|
response = await buffered.receive_until(b"\n", 50)
|
||||||
|
status, length = response.split(b" ")
|
||||||
|
if status not in (b"RETURN", b"EXCEPTION"):
|
||||||
|
raise RuntimeError(
|
||||||
|
f"Worker process returned unexpected response: {response!r}"
|
||||||
|
)
|
||||||
|
|
||||||
|
pickled_response = await buffered.receive_exactly(int(length))
|
||||||
|
except BaseException as exc:
|
||||||
|
workers.discard(process)
|
||||||
|
try:
|
||||||
|
process.kill()
|
||||||
|
with CancelScope(shield=True):
|
||||||
|
await process.aclose()
|
||||||
|
except ProcessLookupError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
if isinstance(exc, get_cancelled_exc_class()):
|
||||||
|
raise
|
||||||
|
else:
|
||||||
|
raise BrokenWorkerProcess from exc
|
||||||
|
|
||||||
|
retval = pickle.loads(pickled_response)
|
||||||
|
if status == b"EXCEPTION":
|
||||||
|
assert isinstance(retval, BaseException)
|
||||||
|
raise retval
|
||||||
|
else:
|
||||||
|
return retval
|
||||||
|
|
||||||
|
# First pickle the request before trying to reserve a worker process
|
||||||
|
await checkpoint_if_cancelled()
|
||||||
|
request = pickle.dumps(("run", func, args), protocol=pickle.HIGHEST_PROTOCOL)
|
||||||
|
|
||||||
|
# If this is the first run in this event loop thread, set up the necessary variables
|
||||||
|
try:
|
||||||
|
workers = _process_pool_workers.get()
|
||||||
|
idle_workers = _process_pool_idle_workers.get()
|
||||||
|
except LookupError:
|
||||||
|
workers = set()
|
||||||
|
idle_workers = deque()
|
||||||
|
_process_pool_workers.set(workers)
|
||||||
|
_process_pool_idle_workers.set(idle_workers)
|
||||||
|
get_async_backend().setup_process_pool_exit_at_shutdown(workers)
|
||||||
|
|
||||||
|
async with limiter or current_default_process_limiter():
|
||||||
|
# Pop processes from the pool (starting from the most recently used) until we
|
||||||
|
# find one that hasn't exited yet
|
||||||
|
process: Process
|
||||||
|
while idle_workers:
|
||||||
|
process, _idle_since = idle_workers.pop()
|
||||||
|
if process.returncode is None:
|
||||||
|
stdin = cast(ByteSendStream, process.stdin)
|
||||||
|
buffered = BufferedByteReceiveStream(
|
||||||
|
cast(ByteReceiveStream, process.stdout)
|
||||||
|
)
|
||||||
|
|
||||||
|
# Prune any other workers that have been idle for WORKER_MAX_IDLE_TIME
|
||||||
|
# seconds or longer
|
||||||
|
now = current_time()
|
||||||
|
killed_processes: list[Process] = []
|
||||||
|
while idle_workers:
|
||||||
|
if now - idle_workers[0][1] < WORKER_MAX_IDLE_TIME:
|
||||||
|
break
|
||||||
|
|
||||||
|
process_to_kill, _idle_since = idle_workers.popleft()
|
||||||
|
process_to_kill.kill()
|
||||||
|
workers.remove(process_to_kill)
|
||||||
|
killed_processes.append(process_to_kill)
|
||||||
|
|
||||||
|
with CancelScope(shield=True):
|
||||||
|
for killed_process in killed_processes:
|
||||||
|
await killed_process.aclose()
|
||||||
|
|
||||||
|
break
|
||||||
|
|
||||||
|
workers.remove(process)
|
||||||
|
else:
|
||||||
|
command = [sys.executable, "-u", "-m", __name__]
|
||||||
|
process = await open_process(
|
||||||
|
command, stdin=subprocess.PIPE, stdout=subprocess.PIPE
|
||||||
|
)
|
||||||
|
try:
|
||||||
|
stdin = cast(ByteSendStream, process.stdin)
|
||||||
|
buffered = BufferedByteReceiveStream(
|
||||||
|
cast(ByteReceiveStream, process.stdout)
|
||||||
|
)
|
||||||
|
with fail_after(20):
|
||||||
|
message = await buffered.receive(6)
|
||||||
|
|
||||||
|
if message != b"READY\n":
|
||||||
|
raise BrokenWorkerProcess(
|
||||||
|
f"Worker process returned unexpected response: {message!r}"
|
||||||
|
)
|
||||||
|
|
||||||
|
main_module_path = getattr(sys.modules["__main__"], "__file__", None)
|
||||||
|
pickled = pickle.dumps(
|
||||||
|
("init", sys.path, main_module_path),
|
||||||
|
protocol=pickle.HIGHEST_PROTOCOL,
|
||||||
|
)
|
||||||
|
await send_raw_command(pickled)
|
||||||
|
except (BrokenWorkerProcess, get_cancelled_exc_class()):
|
||||||
|
raise
|
||||||
|
except BaseException as exc:
|
||||||
|
process.kill()
|
||||||
|
raise BrokenWorkerProcess(
|
||||||
|
"Error during worker process initialization"
|
||||||
|
) from exc
|
||||||
|
|
||||||
|
workers.add(process)
|
||||||
|
|
||||||
|
with CancelScope(shield=not cancellable):
|
||||||
|
try:
|
||||||
|
return cast(T_Retval, await send_raw_command(request))
|
||||||
|
finally:
|
||||||
|
if process in workers:
|
||||||
|
idle_workers.append((process, current_time()))
|
||||||
|
|
||||||
|
|
||||||
|
def current_default_process_limiter() -> CapacityLimiter:
|
||||||
|
"""
|
||||||
|
Return the capacity limiter that is used by default to limit the number of worker
|
||||||
|
processes.
|
||||||
|
|
||||||
|
:return: a capacity limiter object
|
||||||
|
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
return _default_process_limiter.get()
|
||||||
|
except LookupError:
|
||||||
|
limiter = CapacityLimiter(os.cpu_count() or 2)
|
||||||
|
_default_process_limiter.set(limiter)
|
||||||
|
return limiter
|
||||||
|
|
||||||
|
|
||||||
|
def process_worker() -> None:
|
||||||
|
# Redirect standard streams to os.devnull so that user code won't interfere with the
|
||||||
|
# parent-worker communication
|
||||||
|
stdin = sys.stdin
|
||||||
|
stdout = sys.stdout
|
||||||
|
sys.stdin = open(os.devnull)
|
||||||
|
sys.stdout = open(os.devnull, "w")
|
||||||
|
sys.stderr = open(os.devnull, "w")
|
||||||
|
|
||||||
|
stdout.buffer.write(b"READY\n")
|
||||||
|
while True:
|
||||||
|
retval = exception = None
|
||||||
|
try:
|
||||||
|
command, *args = pickle.load(stdin.buffer)
|
||||||
|
except EOFError:
|
||||||
|
return
|
||||||
|
except BaseException as exc:
|
||||||
|
exception = exc
|
||||||
|
else:
|
||||||
|
if command == "run":
|
||||||
|
func, args = args
|
||||||
|
try:
|
||||||
|
retval = func(*args)
|
||||||
|
except BaseException as exc:
|
||||||
|
exception = exc
|
||||||
|
elif command == "init":
|
||||||
|
main_module_path: str | None
|
||||||
|
sys.path, main_module_path = args
|
||||||
|
del sys.modules["__main__"]
|
||||||
|
if main_module_path and os.path.isfile(main_module_path):
|
||||||
|
# Load the parent's main module but as __mp_main__ instead of
|
||||||
|
# __main__ (like multiprocessing does) to avoid infinite recursion
|
||||||
|
try:
|
||||||
|
main = ModuleType("__mp_main__")
|
||||||
|
main_content = runpy.run_path(
|
||||||
|
main_module_path, run_name="__mp_main__"
|
||||||
|
)
|
||||||
|
main.__dict__.update(main_content)
|
||||||
|
sys.modules["__main__"] = sys.modules["__mp_main__"] = main
|
||||||
|
except BaseException as exc:
|
||||||
|
exception = exc
|
||||||
|
try:
|
||||||
|
if exception is not None:
|
||||||
|
status = b"EXCEPTION"
|
||||||
|
pickled = pickle.dumps(exception, pickle.HIGHEST_PROTOCOL)
|
||||||
|
else:
|
||||||
|
status = b"RETURN"
|
||||||
|
pickled = pickle.dumps(retval, pickle.HIGHEST_PROTOCOL)
|
||||||
|
except BaseException as exc:
|
||||||
|
exception = exc
|
||||||
|
status = b"EXCEPTION"
|
||||||
|
pickled = pickle.dumps(exc, pickle.HIGHEST_PROTOCOL)
|
||||||
|
|
||||||
|
stdout.buffer.write(b"%s %d\n" % (status, len(pickled)))
|
||||||
|
stdout.buffer.write(pickled)
|
||||||
|
|
||||||
|
# Respect SIGTERM
|
||||||
|
if isinstance(exception, SystemExit):
|
||||||
|
raise exception
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
process_worker()
|
||||||
@@ -0,0 +1,80 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
__all__ = (
|
||||||
|
"current_default_thread_limiter",
|
||||||
|
"run_sync",
|
||||||
|
)
|
||||||
|
|
||||||
|
import sys
|
||||||
|
from collections.abc import Callable
|
||||||
|
from typing import TYPE_CHECKING, TypeVar
|
||||||
|
from warnings import warn
|
||||||
|
|
||||||
|
from ._core._eventloop import get_async_backend
|
||||||
|
|
||||||
|
if TYPE_CHECKING:
|
||||||
|
from ._core._synchronization import CapacityLimiter
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import TypeVarTuple, Unpack
|
||||||
|
else:
|
||||||
|
from typing_extensions import TypeVarTuple, Unpack
|
||||||
|
|
||||||
|
T_Retval = TypeVar("T_Retval")
|
||||||
|
PosArgsT = TypeVarTuple("PosArgsT")
|
||||||
|
|
||||||
|
|
||||||
|
async def run_sync(
|
||||||
|
func: Callable[[Unpack[PosArgsT]], T_Retval],
|
||||||
|
*args: Unpack[PosArgsT],
|
||||||
|
abandon_on_cancel: bool = False,
|
||||||
|
cancellable: bool | None = None,
|
||||||
|
limiter: CapacityLimiter | None = None,
|
||||||
|
) -> T_Retval:
|
||||||
|
"""
|
||||||
|
Call the given function with the given arguments in a worker thread.
|
||||||
|
|
||||||
|
If the ``abandon_on_cancel`` option is enabled and the task waiting for its
|
||||||
|
completion is cancelled, the thread will still run its course but its
|
||||||
|
return value (or any raised exception) will be ignored.
|
||||||
|
|
||||||
|
:param func: a callable
|
||||||
|
:param args: positional arguments for the callable
|
||||||
|
:param abandon_on_cancel: ``True`` to abandon the thread (leaving it to run
|
||||||
|
unchecked on own) if the host task is cancelled, ``False`` to ignore
|
||||||
|
cancellations in the host task until the operation has completed in the worker
|
||||||
|
thread
|
||||||
|
:param cancellable: deprecated alias of ``abandon_on_cancel``; will override
|
||||||
|
``abandon_on_cancel`` if both parameters are passed
|
||||||
|
:param limiter: capacity limiter to use to limit the total amount of threads running
|
||||||
|
(if omitted, the default limiter is used)
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
:return: an awaitable that yields the return value of the function.
|
||||||
|
|
||||||
|
"""
|
||||||
|
if cancellable is not None:
|
||||||
|
abandon_on_cancel = cancellable
|
||||||
|
warn(
|
||||||
|
"The `cancellable=` keyword argument to `anyio.to_thread.run_sync` is "
|
||||||
|
"deprecated since AnyIO 4.1.0; use `abandon_on_cancel=` instead",
|
||||||
|
DeprecationWarning,
|
||||||
|
stacklevel=2,
|
||||||
|
)
|
||||||
|
|
||||||
|
return await get_async_backend().run_sync_in_worker_thread(
|
||||||
|
func, args, abandon_on_cancel=abandon_on_cancel, limiter=limiter
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def current_default_thread_limiter() -> CapacityLimiter:
|
||||||
|
"""
|
||||||
|
Return the capacity limiter that is used by default to limit the number of
|
||||||
|
concurrent threads.
|
||||||
|
|
||||||
|
:return: a capacity limiter object
|
||||||
|
:raises NoEventLoopError: if no supported asynchronous event loop is running in the
|
||||||
|
current thread
|
||||||
|
|
||||||
|
"""
|
||||||
|
return get_async_backend().current_default_thread_limiter()
|
||||||
@@ -0,0 +1,104 @@
|
|||||||
|
# SPDX-License-Identifier: MIT
|
||||||
|
|
||||||
|
"""
|
||||||
|
Classes Without Boilerplate
|
||||||
|
"""
|
||||||
|
|
||||||
|
from functools import partial
|
||||||
|
from typing import Callable, Literal, Protocol
|
||||||
|
|
||||||
|
from . import converters, exceptions, filters, setters, validators
|
||||||
|
from ._cmp import cmp_using
|
||||||
|
from ._config import get_run_validators, set_run_validators
|
||||||
|
from ._funcs import asdict, assoc, astuple, has, resolve_types
|
||||||
|
from ._make import (
|
||||||
|
NOTHING,
|
||||||
|
Attribute,
|
||||||
|
Converter,
|
||||||
|
Factory,
|
||||||
|
_Nothing,
|
||||||
|
attrib,
|
||||||
|
attrs,
|
||||||
|
evolve,
|
||||||
|
fields,
|
||||||
|
fields_dict,
|
||||||
|
make_class,
|
||||||
|
validate,
|
||||||
|
)
|
||||||
|
from ._next_gen import define, field, frozen, mutable
|
||||||
|
from ._version_info import VersionInfo
|
||||||
|
|
||||||
|
|
||||||
|
s = attributes = attrs
|
||||||
|
ib = attr = attrib
|
||||||
|
dataclass = partial(attrs, auto_attribs=True) # happy Easter ;)
|
||||||
|
|
||||||
|
|
||||||
|
class AttrsInstance(Protocol):
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
NothingType = Literal[_Nothing.NOTHING]
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
"NOTHING",
|
||||||
|
"Attribute",
|
||||||
|
"AttrsInstance",
|
||||||
|
"Converter",
|
||||||
|
"Factory",
|
||||||
|
"NothingType",
|
||||||
|
"asdict",
|
||||||
|
"assoc",
|
||||||
|
"astuple",
|
||||||
|
"attr",
|
||||||
|
"attrib",
|
||||||
|
"attributes",
|
||||||
|
"attrs",
|
||||||
|
"cmp_using",
|
||||||
|
"converters",
|
||||||
|
"define",
|
||||||
|
"evolve",
|
||||||
|
"exceptions",
|
||||||
|
"field",
|
||||||
|
"fields",
|
||||||
|
"fields_dict",
|
||||||
|
"filters",
|
||||||
|
"frozen",
|
||||||
|
"get_run_validators",
|
||||||
|
"has",
|
||||||
|
"ib",
|
||||||
|
"make_class",
|
||||||
|
"mutable",
|
||||||
|
"resolve_types",
|
||||||
|
"s",
|
||||||
|
"set_run_validators",
|
||||||
|
"setters",
|
||||||
|
"validate",
|
||||||
|
"validators",
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
def _make_getattr(mod_name: str) -> Callable:
|
||||||
|
"""
|
||||||
|
Create a metadata proxy for packaging information that uses *mod_name* in
|
||||||
|
its warnings and errors.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __getattr__(name: str) -> str:
|
||||||
|
if name not in ("__version__", "__version_info__"):
|
||||||
|
msg = f"module {mod_name} has no attribute {name}"
|
||||||
|
raise AttributeError(msg)
|
||||||
|
|
||||||
|
from importlib.metadata import metadata
|
||||||
|
|
||||||
|
meta = metadata("attrs")
|
||||||
|
|
||||||
|
if name == "__version_info__":
|
||||||
|
return VersionInfo._from_version_string(meta["version"])
|
||||||
|
|
||||||
|
return meta["version"]
|
||||||
|
|
||||||
|
return __getattr__
|
||||||
|
|
||||||
|
|
||||||
|
__getattr__ = _make_getattr(__name__)
|
||||||
@@ -0,0 +1,389 @@
|
|||||||
|
import enum
|
||||||
|
import sys
|
||||||
|
|
||||||
|
from typing import (
|
||||||
|
Any,
|
||||||
|
Callable,
|
||||||
|
Generic,
|
||||||
|
Literal,
|
||||||
|
Mapping,
|
||||||
|
Protocol,
|
||||||
|
Sequence,
|
||||||
|
TypeVar,
|
||||||
|
overload,
|
||||||
|
)
|
||||||
|
|
||||||
|
# `import X as X` is required to make these public
|
||||||
|
from . import converters as converters
|
||||||
|
from . import exceptions as exceptions
|
||||||
|
from . import filters as filters
|
||||||
|
from . import setters as setters
|
||||||
|
from . import validators as validators
|
||||||
|
from ._cmp import cmp_using as cmp_using
|
||||||
|
from ._typing_compat import AttrsInstance_
|
||||||
|
from ._version_info import VersionInfo
|
||||||
|
from attrs import (
|
||||||
|
define as define,
|
||||||
|
field as field,
|
||||||
|
mutable as mutable,
|
||||||
|
frozen as frozen,
|
||||||
|
_EqOrderType,
|
||||||
|
_ValidatorType,
|
||||||
|
_ConverterType,
|
||||||
|
_ReprArgType,
|
||||||
|
_OnSetAttrType,
|
||||||
|
_OnSetAttrArgType,
|
||||||
|
_FieldTransformer,
|
||||||
|
_ValidatorArgType,
|
||||||
|
)
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 10):
|
||||||
|
from typing import TypeGuard, TypeAlias
|
||||||
|
else:
|
||||||
|
from typing_extensions import TypeGuard, TypeAlias
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 11):
|
||||||
|
from typing import dataclass_transform
|
||||||
|
else:
|
||||||
|
from typing_extensions import dataclass_transform
|
||||||
|
|
||||||
|
__version__: str
|
||||||
|
__version_info__: VersionInfo
|
||||||
|
__title__: str
|
||||||
|
__description__: str
|
||||||
|
__url__: str
|
||||||
|
__uri__: str
|
||||||
|
__author__: str
|
||||||
|
__email__: str
|
||||||
|
__license__: str
|
||||||
|
__copyright__: str
|
||||||
|
|
||||||
|
_T = TypeVar("_T")
|
||||||
|
_C = TypeVar("_C", bound=type)
|
||||||
|
|
||||||
|
_FilterType = Callable[["Attribute[_T]", _T], bool]
|
||||||
|
|
||||||
|
# We subclass this here to keep the protocol's qualified name clean.
|
||||||
|
class AttrsInstance(AttrsInstance_, Protocol):
|
||||||
|
pass
|
||||||
|
|
||||||
|
_A = TypeVar("_A", bound=type[AttrsInstance])
|
||||||
|
|
||||||
|
class _Nothing(enum.Enum):
|
||||||
|
NOTHING = enum.auto()
|
||||||
|
|
||||||
|
NOTHING = _Nothing.NOTHING
|
||||||
|
NothingType: TypeAlias = Literal[_Nothing.NOTHING]
|
||||||
|
|
||||||
|
# NOTE: Factory lies about its return type to make this possible:
|
||||||
|
# `x: List[int] # = Factory(list)`
|
||||||
|
# Work around mypy issue #4554 in the common case by using an overload.
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def Factory(factory: Callable[[], _T]) -> _T: ...
|
||||||
|
@overload
|
||||||
|
def Factory(
|
||||||
|
factory: Callable[[Any], _T],
|
||||||
|
takes_self: Literal[True],
|
||||||
|
) -> _T: ...
|
||||||
|
@overload
|
||||||
|
def Factory(
|
||||||
|
factory: Callable[[], _T],
|
||||||
|
takes_self: Literal[False],
|
||||||
|
) -> _T: ...
|
||||||
|
|
||||||
|
In = TypeVar("In")
|
||||||
|
Out = TypeVar("Out")
|
||||||
|
|
||||||
|
class Converter(Generic[In, Out]):
|
||||||
|
@overload
|
||||||
|
def __init__(self, converter: Callable[[In], Out]) -> None: ...
|
||||||
|
@overload
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
converter: Callable[[In, AttrsInstance, Attribute], Out],
|
||||||
|
*,
|
||||||
|
takes_self: Literal[True],
|
||||||
|
takes_field: Literal[True],
|
||||||
|
) -> None: ...
|
||||||
|
@overload
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
converter: Callable[[In, Attribute], Out],
|
||||||
|
*,
|
||||||
|
takes_field: Literal[True],
|
||||||
|
) -> None: ...
|
||||||
|
@overload
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
converter: Callable[[In, AttrsInstance], Out],
|
||||||
|
*,
|
||||||
|
takes_self: Literal[True],
|
||||||
|
) -> None: ...
|
||||||
|
|
||||||
|
class Attribute(Generic[_T]):
|
||||||
|
name: str
|
||||||
|
default: _T | None
|
||||||
|
validator: _ValidatorType[_T] | None
|
||||||
|
repr: _ReprArgType
|
||||||
|
cmp: _EqOrderType
|
||||||
|
eq: _EqOrderType
|
||||||
|
order: _EqOrderType
|
||||||
|
hash: bool | None
|
||||||
|
init: bool
|
||||||
|
converter: Converter | None
|
||||||
|
metadata: dict[Any, Any]
|
||||||
|
type: type[_T] | None
|
||||||
|
kw_only: bool
|
||||||
|
on_setattr: _OnSetAttrType
|
||||||
|
alias: str | None
|
||||||
|
|
||||||
|
def evolve(self, **changes: Any) -> "Attribute[Any]": ...
|
||||||
|
|
||||||
|
# NOTE: We had several choices for the annotation to use for type arg:
|
||||||
|
# 1) Type[_T]
|
||||||
|
# - Pros: Handles simple cases correctly
|
||||||
|
# - Cons: Might produce less informative errors in the case of conflicting
|
||||||
|
# TypeVars e.g. `attr.ib(default='bad', type=int)`
|
||||||
|
# 2) Callable[..., _T]
|
||||||
|
# - Pros: Better error messages than #1 for conflicting TypeVars
|
||||||
|
# - Cons: Terrible error messages for validator checks.
|
||||||
|
# e.g. attr.ib(type=int, validator=validate_str)
|
||||||
|
# -> error: Cannot infer function type argument
|
||||||
|
# 3) type (and do all of the work in the mypy plugin)
|
||||||
|
# - Pros: Simple here, and we could customize the plugin with our own errors.
|
||||||
|
# - Cons: Would need to write mypy plugin code to handle all the cases.
|
||||||
|
# We chose option #1.
|
||||||
|
|
||||||
|
# `attr` lies about its return type to make the following possible:
|
||||||
|
# attr() -> Any
|
||||||
|
# attr(8) -> int
|
||||||
|
# attr(validator=<some callable>) -> Whatever the callable expects.
|
||||||
|
# This makes this type of assignments possible:
|
||||||
|
# x: int = attr(8)
|
||||||
|
#
|
||||||
|
# This form catches explicit None or no default but with no other arguments
|
||||||
|
# returns Any.
|
||||||
|
@overload
|
||||||
|
def attrib(
|
||||||
|
default: None = ...,
|
||||||
|
validator: None = ...,
|
||||||
|
repr: _ReprArgType = ...,
|
||||||
|
cmp: _EqOrderType | None = ...,
|
||||||
|
hash: bool | None = ...,
|
||||||
|
init: bool = ...,
|
||||||
|
metadata: Mapping[Any, Any] | None = ...,
|
||||||
|
type: None = ...,
|
||||||
|
converter: None = ...,
|
||||||
|
factory: None = ...,
|
||||||
|
kw_only: bool | None = ...,
|
||||||
|
eq: _EqOrderType | None = ...,
|
||||||
|
order: _EqOrderType | None = ...,
|
||||||
|
on_setattr: _OnSetAttrArgType | None = ...,
|
||||||
|
alias: str | None = ...,
|
||||||
|
) -> Any: ...
|
||||||
|
|
||||||
|
# This form catches an explicit None or no default and infers the type from the
|
||||||
|
# other arguments.
|
||||||
|
@overload
|
||||||
|
def attrib(
|
||||||
|
default: None = ...,
|
||||||
|
validator: _ValidatorArgType[_T] | None = ...,
|
||||||
|
repr: _ReprArgType = ...,
|
||||||
|
cmp: _EqOrderType | None = ...,
|
||||||
|
hash: bool | None = ...,
|
||||||
|
init: bool = ...,
|
||||||
|
metadata: Mapping[Any, Any] | None = ...,
|
||||||
|
type: type[_T] | None = ...,
|
||||||
|
converter: _ConverterType
|
||||||
|
| list[_ConverterType]
|
||||||
|
| tuple[_ConverterType]
|
||||||
|
| None = ...,
|
||||||
|
factory: Callable[[], _T] | None = ...,
|
||||||
|
kw_only: bool | None = ...,
|
||||||
|
eq: _EqOrderType | None = ...,
|
||||||
|
order: _EqOrderType | None = ...,
|
||||||
|
on_setattr: _OnSetAttrArgType | None = ...,
|
||||||
|
alias: str | None = ...,
|
||||||
|
) -> _T: ...
|
||||||
|
|
||||||
|
# This form catches an explicit default argument.
|
||||||
|
@overload
|
||||||
|
def attrib(
|
||||||
|
default: _T,
|
||||||
|
validator: _ValidatorArgType[_T] | None = ...,
|
||||||
|
repr: _ReprArgType = ...,
|
||||||
|
cmp: _EqOrderType | None = ...,
|
||||||
|
hash: bool | None = ...,
|
||||||
|
init: bool = ...,
|
||||||
|
metadata: Mapping[Any, Any] | None = ...,
|
||||||
|
type: type[_T] | None = ...,
|
||||||
|
converter: _ConverterType
|
||||||
|
| list[_ConverterType]
|
||||||
|
| tuple[_ConverterType]
|
||||||
|
| None = ...,
|
||||||
|
factory: Callable[[], _T] | None = ...,
|
||||||
|
kw_only: bool | None = ...,
|
||||||
|
eq: _EqOrderType | None = ...,
|
||||||
|
order: _EqOrderType | None = ...,
|
||||||
|
on_setattr: _OnSetAttrArgType | None = ...,
|
||||||
|
alias: str | None = ...,
|
||||||
|
) -> _T: ...
|
||||||
|
|
||||||
|
# This form covers type=non-Type: e.g. forward references (str), Any
|
||||||
|
@overload
|
||||||
|
def attrib(
|
||||||
|
default: _T | None = ...,
|
||||||
|
validator: _ValidatorArgType[_T] | None = ...,
|
||||||
|
repr: _ReprArgType = ...,
|
||||||
|
cmp: _EqOrderType | None = ...,
|
||||||
|
hash: bool | None = ...,
|
||||||
|
init: bool = ...,
|
||||||
|
metadata: Mapping[Any, Any] | None = ...,
|
||||||
|
type: object = ...,
|
||||||
|
converter: _ConverterType
|
||||||
|
| list[_ConverterType]
|
||||||
|
| tuple[_ConverterType]
|
||||||
|
| None = ...,
|
||||||
|
factory: Callable[[], _T] | None = ...,
|
||||||
|
kw_only: bool | None = ...,
|
||||||
|
eq: _EqOrderType | None = ...,
|
||||||
|
order: _EqOrderType | None = ...,
|
||||||
|
on_setattr: _OnSetAttrArgType | None = ...,
|
||||||
|
alias: str | None = ...,
|
||||||
|
) -> Any: ...
|
||||||
|
@overload
|
||||||
|
@dataclass_transform(order_default=True, field_specifiers=(attrib, field))
|
||||||
|
def attrs(
|
||||||
|
maybe_cls: _C,
|
||||||
|
these: dict[str, Any] | None = ...,
|
||||||
|
repr_ns: str | None = ...,
|
||||||
|
repr: bool = ...,
|
||||||
|
cmp: _EqOrderType | None = ...,
|
||||||
|
hash: bool | None = ...,
|
||||||
|
init: bool = ...,
|
||||||
|
slots: bool = ...,
|
||||||
|
frozen: bool = ...,
|
||||||
|
weakref_slot: bool = ...,
|
||||||
|
str: bool = ...,
|
||||||
|
auto_attribs: bool = ...,
|
||||||
|
kw_only: bool = ...,
|
||||||
|
cache_hash: bool = ...,
|
||||||
|
auto_exc: bool = ...,
|
||||||
|
eq: _EqOrderType | None = ...,
|
||||||
|
order: _EqOrderType | None = ...,
|
||||||
|
auto_detect: bool = ...,
|
||||||
|
collect_by_mro: bool = ...,
|
||||||
|
getstate_setstate: bool | None = ...,
|
||||||
|
on_setattr: _OnSetAttrArgType | None = ...,
|
||||||
|
field_transformer: _FieldTransformer | None = ...,
|
||||||
|
match_args: bool = ...,
|
||||||
|
unsafe_hash: bool | None = ...,
|
||||||
|
) -> _C: ...
|
||||||
|
@overload
|
||||||
|
@dataclass_transform(order_default=True, field_specifiers=(attrib, field))
|
||||||
|
def attrs(
|
||||||
|
maybe_cls: None = ...,
|
||||||
|
these: dict[str, Any] | None = ...,
|
||||||
|
repr_ns: str | None = ...,
|
||||||
|
repr: bool = ...,
|
||||||
|
cmp: _EqOrderType | None = ...,
|
||||||
|
hash: bool | None = ...,
|
||||||
|
init: bool = ...,
|
||||||
|
slots: bool = ...,
|
||||||
|
frozen: bool = ...,
|
||||||
|
weakref_slot: bool = ...,
|
||||||
|
str: bool = ...,
|
||||||
|
auto_attribs: bool = ...,
|
||||||
|
kw_only: bool = ...,
|
||||||
|
cache_hash: bool = ...,
|
||||||
|
auto_exc: bool = ...,
|
||||||
|
eq: _EqOrderType | None = ...,
|
||||||
|
order: _EqOrderType | None = ...,
|
||||||
|
auto_detect: bool = ...,
|
||||||
|
collect_by_mro: bool = ...,
|
||||||
|
getstate_setstate: bool | None = ...,
|
||||||
|
on_setattr: _OnSetAttrArgType | None = ...,
|
||||||
|
field_transformer: _FieldTransformer | None = ...,
|
||||||
|
match_args: bool = ...,
|
||||||
|
unsafe_hash: bool | None = ...,
|
||||||
|
) -> Callable[[_C], _C]: ...
|
||||||
|
def fields(cls: type[AttrsInstance] | AttrsInstance) -> Any: ...
|
||||||
|
def fields_dict(cls: type[AttrsInstance]) -> dict[str, Attribute[Any]]: ...
|
||||||
|
def validate(inst: AttrsInstance) -> None: ...
|
||||||
|
def resolve_types(
|
||||||
|
cls: _A,
|
||||||
|
globalns: dict[str, Any] | None = ...,
|
||||||
|
localns: dict[str, Any] | None = ...,
|
||||||
|
attribs: list[Attribute[Any]] | None = ...,
|
||||||
|
include_extras: bool = ...,
|
||||||
|
) -> _A: ...
|
||||||
|
|
||||||
|
# TODO: add support for returning a proper attrs class from the mypy plugin
|
||||||
|
# we use Any instead of _CountingAttr so that e.g. `make_class('Foo',
|
||||||
|
# [attr.ib()])` is valid
|
||||||
|
def make_class(
|
||||||
|
name: str,
|
||||||
|
attrs: list[str] | tuple[str, ...] | dict[str, Any],
|
||||||
|
bases: tuple[type, ...] = ...,
|
||||||
|
class_body: dict[str, Any] | None = ...,
|
||||||
|
repr_ns: str | None = ...,
|
||||||
|
repr: bool = ...,
|
||||||
|
cmp: _EqOrderType | None = ...,
|
||||||
|
hash: bool | None = ...,
|
||||||
|
init: bool = ...,
|
||||||
|
slots: bool = ...,
|
||||||
|
frozen: bool = ...,
|
||||||
|
weakref_slot: bool = ...,
|
||||||
|
str: bool = ...,
|
||||||
|
auto_attribs: bool = ...,
|
||||||
|
kw_only: bool = ...,
|
||||||
|
cache_hash: bool = ...,
|
||||||
|
auto_exc: bool = ...,
|
||||||
|
eq: _EqOrderType | None = ...,
|
||||||
|
order: _EqOrderType | None = ...,
|
||||||
|
collect_by_mro: bool = ...,
|
||||||
|
on_setattr: _OnSetAttrArgType | None = ...,
|
||||||
|
field_transformer: _FieldTransformer | None = ...,
|
||||||
|
) -> type: ...
|
||||||
|
|
||||||
|
# _funcs --
|
||||||
|
|
||||||
|
# TODO: add support for returning TypedDict from the mypy plugin
|
||||||
|
# FIXME: asdict/astuple do not honor their factory args. Waiting on one of
|
||||||
|
# these:
|
||||||
|
# https://github.com/python/mypy/issues/4236
|
||||||
|
# https://github.com/python/typing/issues/253
|
||||||
|
# XXX: remember to fix attrs.asdict/astuple too!
|
||||||
|
def asdict(
|
||||||
|
inst: AttrsInstance,
|
||||||
|
recurse: bool = ...,
|
||||||
|
filter: _FilterType[Any] | None = ...,
|
||||||
|
dict_factory: type[Mapping[Any, Any]] = ...,
|
||||||
|
retain_collection_types: bool = ...,
|
||||||
|
value_serializer: Callable[[type, Attribute[Any], Any], Any] | None = ...,
|
||||||
|
tuple_keys: bool | None = ...,
|
||||||
|
) -> dict[str, Any]: ...
|
||||||
|
|
||||||
|
# TODO: add support for returning NamedTuple from the mypy plugin
|
||||||
|
def astuple(
|
||||||
|
inst: AttrsInstance,
|
||||||
|
recurse: bool = ...,
|
||||||
|
filter: _FilterType[Any] | None = ...,
|
||||||
|
tuple_factory: type[Sequence[Any]] = ...,
|
||||||
|
retain_collection_types: bool = ...,
|
||||||
|
) -> tuple[Any, ...]: ...
|
||||||
|
def has(cls: type) -> TypeGuard[type[AttrsInstance]]: ...
|
||||||
|
def assoc(inst: _T, **changes: Any) -> _T: ...
|
||||||
|
def evolve(inst: _T, **changes: Any) -> _T: ...
|
||||||
|
|
||||||
|
# _config --
|
||||||
|
|
||||||
|
def set_run_validators(run: bool) -> None: ...
|
||||||
|
def get_run_validators() -> bool: ...
|
||||||
|
|
||||||
|
# aliases --
|
||||||
|
|
||||||
|
s = attributes = attrs
|
||||||
|
ib = attr = attrib
|
||||||
|
dataclass = attrs # Technically, partial(attrs, auto_attribs=True) ;)
|
||||||
@@ -0,0 +1,160 @@
|
|||||||
|
# SPDX-License-Identifier: MIT
|
||||||
|
|
||||||
|
|
||||||
|
import functools
|
||||||
|
import types
|
||||||
|
|
||||||
|
from ._make import __ne__
|
||||||
|
|
||||||
|
|
||||||
|
_operation_names = {"eq": "==", "lt": "<", "le": "<=", "gt": ">", "ge": ">="}
|
||||||
|
|
||||||
|
|
||||||
|
def cmp_using(
|
||||||
|
eq=None,
|
||||||
|
lt=None,
|
||||||
|
le=None,
|
||||||
|
gt=None,
|
||||||
|
ge=None,
|
||||||
|
require_same_type=True,
|
||||||
|
class_name="Comparable",
|
||||||
|
):
|
||||||
|
"""
|
||||||
|
Create a class that can be passed into `attrs.field`'s ``eq``, ``order``,
|
||||||
|
and ``cmp`` arguments to customize field comparison.
|
||||||
|
|
||||||
|
The resulting class will have a full set of ordering methods if at least
|
||||||
|
one of ``{lt, le, gt, ge}`` and ``eq`` are provided.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
eq (typing.Callable | None):
|
||||||
|
Callable used to evaluate equality of two objects.
|
||||||
|
|
||||||
|
lt (typing.Callable | None):
|
||||||
|
Callable used to evaluate whether one object is less than another
|
||||||
|
object.
|
||||||
|
|
||||||
|
le (typing.Callable | None):
|
||||||
|
Callable used to evaluate whether one object is less than or equal
|
||||||
|
to another object.
|
||||||
|
|
||||||
|
gt (typing.Callable | None):
|
||||||
|
Callable used to evaluate whether one object is greater than
|
||||||
|
another object.
|
||||||
|
|
||||||
|
ge (typing.Callable | None):
|
||||||
|
Callable used to evaluate whether one object is greater than or
|
||||||
|
equal to another object.
|
||||||
|
|
||||||
|
require_same_type (bool):
|
||||||
|
When `True`, equality and ordering methods will return
|
||||||
|
`NotImplemented` if objects are not of the same type.
|
||||||
|
|
||||||
|
class_name (str | None): Name of class. Defaults to "Comparable".
|
||||||
|
|
||||||
|
See `comparison` for more details.
|
||||||
|
|
||||||
|
.. versionadded:: 21.1.0
|
||||||
|
"""
|
||||||
|
|
||||||
|
body = {
|
||||||
|
"__slots__": ["value"],
|
||||||
|
"__init__": _make_init(),
|
||||||
|
"_requirements": [],
|
||||||
|
"_is_comparable_to": _is_comparable_to,
|
||||||
|
}
|
||||||
|
|
||||||
|
# Add operations.
|
||||||
|
num_order_functions = 0
|
||||||
|
has_eq_function = False
|
||||||
|
|
||||||
|
if eq is not None:
|
||||||
|
has_eq_function = True
|
||||||
|
body["__eq__"] = _make_operator("eq", eq)
|
||||||
|
body["__ne__"] = __ne__
|
||||||
|
|
||||||
|
if lt is not None:
|
||||||
|
num_order_functions += 1
|
||||||
|
body["__lt__"] = _make_operator("lt", lt)
|
||||||
|
|
||||||
|
if le is not None:
|
||||||
|
num_order_functions += 1
|
||||||
|
body["__le__"] = _make_operator("le", le)
|
||||||
|
|
||||||
|
if gt is not None:
|
||||||
|
num_order_functions += 1
|
||||||
|
body["__gt__"] = _make_operator("gt", gt)
|
||||||
|
|
||||||
|
if ge is not None:
|
||||||
|
num_order_functions += 1
|
||||||
|
body["__ge__"] = _make_operator("ge", ge)
|
||||||
|
|
||||||
|
type_ = types.new_class(
|
||||||
|
class_name, (object,), {}, lambda ns: ns.update(body)
|
||||||
|
)
|
||||||
|
|
||||||
|
# Add same type requirement.
|
||||||
|
if require_same_type:
|
||||||
|
type_._requirements.append(_check_same_type)
|
||||||
|
|
||||||
|
# Add total ordering if at least one operation was defined.
|
||||||
|
if 0 < num_order_functions < 4:
|
||||||
|
if not has_eq_function:
|
||||||
|
# functools.total_ordering requires __eq__ to be defined,
|
||||||
|
# so raise early error here to keep a nice stack.
|
||||||
|
msg = "eq must be define is order to complete ordering from lt, le, gt, ge."
|
||||||
|
raise ValueError(msg)
|
||||||
|
type_ = functools.total_ordering(type_)
|
||||||
|
|
||||||
|
return type_
|
||||||
|
|
||||||
|
|
||||||
|
def _make_init():
|
||||||
|
"""
|
||||||
|
Create __init__ method.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, value):
|
||||||
|
"""
|
||||||
|
Initialize object with *value*.
|
||||||
|
"""
|
||||||
|
self.value = value
|
||||||
|
|
||||||
|
return __init__
|
||||||
|
|
||||||
|
|
||||||
|
def _make_operator(name, func):
|
||||||
|
"""
|
||||||
|
Create operator method.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def method(self, other):
|
||||||
|
if not self._is_comparable_to(other):
|
||||||
|
return NotImplemented
|
||||||
|
|
||||||
|
result = func(self.value, other.value)
|
||||||
|
if result is NotImplemented:
|
||||||
|
return NotImplemented
|
||||||
|
|
||||||
|
return result
|
||||||
|
|
||||||
|
method.__name__ = f"__{name}__"
|
||||||
|
method.__doc__ = (
|
||||||
|
f"Return a {_operation_names[name]} b. Computed by attrs."
|
||||||
|
)
|
||||||
|
|
||||||
|
return method
|
||||||
|
|
||||||
|
|
||||||
|
def _is_comparable_to(self, other):
|
||||||
|
"""
|
||||||
|
Check whether `other` is comparable to `self`.
|
||||||
|
"""
|
||||||
|
return all(func(self, other) for func in self._requirements)
|
||||||
|
|
||||||
|
|
||||||
|
def _check_same_type(self, other):
|
||||||
|
"""
|
||||||
|
Return True if *self* and *other* are of the same type, False otherwise.
|
||||||
|
"""
|
||||||
|
return other.value.__class__ is self.value.__class__
|
||||||
@@ -0,0 +1,13 @@
|
|||||||
|
from typing import Any, Callable
|
||||||
|
|
||||||
|
_CompareWithType = Callable[[Any, Any], bool]
|
||||||
|
|
||||||
|
def cmp_using(
|
||||||
|
eq: _CompareWithType | None = ...,
|
||||||
|
lt: _CompareWithType | None = ...,
|
||||||
|
le: _CompareWithType | None = ...,
|
||||||
|
gt: _CompareWithType | None = ...,
|
||||||
|
ge: _CompareWithType | None = ...,
|
||||||
|
require_same_type: bool = ...,
|
||||||
|
class_name: str = ...,
|
||||||
|
) -> type: ...
|
||||||
@@ -0,0 +1,99 @@
|
|||||||
|
# SPDX-License-Identifier: MIT
|
||||||
|
|
||||||
|
import inspect
|
||||||
|
import platform
|
||||||
|
import sys
|
||||||
|
import threading
|
||||||
|
|
||||||
|
from collections.abc import Mapping, Sequence # noqa: F401
|
||||||
|
from typing import _GenericAlias
|
||||||
|
|
||||||
|
|
||||||
|
PYPY = platform.python_implementation() == "PyPy"
|
||||||
|
PY_3_10_PLUS = sys.version_info[:2] >= (3, 10)
|
||||||
|
PY_3_11_PLUS = sys.version_info[:2] >= (3, 11)
|
||||||
|
PY_3_12_PLUS = sys.version_info[:2] >= (3, 12)
|
||||||
|
PY_3_13_PLUS = sys.version_info[:2] >= (3, 13)
|
||||||
|
PY_3_14_PLUS = sys.version_info[:2] >= (3, 14)
|
||||||
|
|
||||||
|
|
||||||
|
if PY_3_14_PLUS:
|
||||||
|
import annotationlib
|
||||||
|
|
||||||
|
# We request forward-ref annotations to not break in the presence of
|
||||||
|
# forward references.
|
||||||
|
|
||||||
|
def _get_annotations(cls):
|
||||||
|
return annotationlib.get_annotations(
|
||||||
|
cls, format=annotationlib.Format.FORWARDREF
|
||||||
|
)
|
||||||
|
|
||||||
|
else:
|
||||||
|
|
||||||
|
def _get_annotations(cls):
|
||||||
|
"""
|
||||||
|
Get annotations for *cls*.
|
||||||
|
"""
|
||||||
|
return cls.__dict__.get("__annotations__", {})
|
||||||
|
|
||||||
|
|
||||||
|
class _AnnotationExtractor:
|
||||||
|
"""
|
||||||
|
Extract type annotations from a callable, returning None whenever there
|
||||||
|
is none.
|
||||||
|
"""
|
||||||
|
|
||||||
|
__slots__ = ["sig"]
|
||||||
|
|
||||||
|
def __init__(self, callable):
|
||||||
|
try:
|
||||||
|
self.sig = inspect.signature(callable)
|
||||||
|
except (ValueError, TypeError): # inspect failed
|
||||||
|
self.sig = None
|
||||||
|
|
||||||
|
def get_first_param_type(self):
|
||||||
|
"""
|
||||||
|
Return the type annotation of the first argument if it's not empty.
|
||||||
|
"""
|
||||||
|
if not self.sig:
|
||||||
|
return None
|
||||||
|
|
||||||
|
params = list(self.sig.parameters.values())
|
||||||
|
if params and params[0].annotation is not inspect.Parameter.empty:
|
||||||
|
return params[0].annotation
|
||||||
|
|
||||||
|
return None
|
||||||
|
|
||||||
|
def get_return_type(self):
|
||||||
|
"""
|
||||||
|
Return the return type if it's not empty.
|
||||||
|
"""
|
||||||
|
if (
|
||||||
|
self.sig
|
||||||
|
and self.sig.return_annotation is not inspect.Signature.empty
|
||||||
|
):
|
||||||
|
return self.sig.return_annotation
|
||||||
|
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
# Thread-local global to track attrs instances which are already being repr'd.
|
||||||
|
# This is needed because there is no other (thread-safe) way to pass info
|
||||||
|
# about the instances that are already being repr'd through the call stack
|
||||||
|
# in order to ensure we don't perform infinite recursion.
|
||||||
|
#
|
||||||
|
# For instance, if an instance contains a dict which contains that instance,
|
||||||
|
# we need to know that we're already repr'ing the outside instance from within
|
||||||
|
# the dict's repr() call.
|
||||||
|
#
|
||||||
|
# This lives here rather than in _make.py so that the functions in _make.py
|
||||||
|
# don't have a direct reference to the thread-local in their globals dict.
|
||||||
|
# If they have such a reference, it breaks cloudpickle.
|
||||||
|
repr_context = threading.local()
|
||||||
|
|
||||||
|
|
||||||
|
def get_generic_base(cl):
|
||||||
|
"""If this is a generic class (A[str]), return the generic base for it."""
|
||||||
|
if cl.__class__ is _GenericAlias:
|
||||||
|
return cl.__origin__
|
||||||
|
return None
|
||||||
Loaded 100 of 993 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user