syshttp 0.1.0__tar.gz

syshttp-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Category rule: nothing dot-prefixed at the repo root gets tracked except the
+# git config files and CI re-included below (a category beats a list).
+/.*
+!/.gitignore
+!/.gitattributes
+!/.github/
+
+# Private agent config. No trailing slash on `.agents`: it is usually a
+# symlink, which a directory-only pattern would not match. `*.local.*` is the
+# unshared override and is never committed.
+.agents
+*.local.*
+CLAUDE*
+.claude
+
+# Build/dist output and generated docs site
+build/
+dist/
+site/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.hypothesis/
+.mypy_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+*.egg-info/
+.pyvenv/
+.venv/
+
+# OS/editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

syshttp-0.1.0/CHANGELOG.md

@@ -0,0 +1,343 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-20
+
+### Added
+
+- `syshttp.client`: an HTTP client on the standard library, so that no feature
+  of syshttp needs `requests` (which only `syshttp.autopatch` patches, in a
+  program that imports it). `HTTPClient(transport=None, *, headers, timeout,
+  deadline, user_agent, env, proxymap, ssl_context, proxy_ssl_context, verify,
+  cookies, tokens, auth_provider, retries, backoff, status_forcelist,
+  cookie_hosts)` sends through a transport and follows redirects with one rule
+  for credentials (`Authorization`, `Cookie` and `Proxy-Authorization` go to the
+  origin they were given for and to no other scheme, host or port). The default `HTTPTransport` (on `http.client`,
+  with a per-thread connection pool, framed bodies, `gzip` / `deflate`
+  decoding and a bounded reply size) routes every request and redirect hop by
+  `proxy.proxy_map(env=env)` (or `proxymap=`): the first entry that accepts a
+  connection, an `http` or `https` proxy (`CONNECT`; an `https` proxy over TLS
+  with the origin's TLS inside it), a URL-prefix gateway, a proxy's
+  credential to the proxy alone; and verifies with the caller's `ssl_context`,
+  else the `CA_BUNDLE` bundle or `verify=<path>`, else the system's context
+  (`proxy_ssl_context` for an `https` proxy or gateway). Cookies (RFC 6265,
+  per origin, on every hop, in a jar by host with `cookies=`), tokens, `_PY`
+  hooks, `auth_provider` and retries (`Retry-After` honoured, a status that
+  outlasts them returned) work as they did on the session. `HTTPResponse`
+  reads its body whole as `content`, `text()` and `json()`.
+- `syshttp.fetch()` (defined in `syshttp.client`, re-exported from the root
+  without importing it): `fetch(url, method="GET", *, headers, data, json,
+  timeout, client, transport, reauth, **client_options)` returns the
+  `HTTPResponse` with its body read, whatever the status; a given `client` is
+  left open and a new one is closed; `reauth` runs once after a 401 or 403.
+- The transport protocol is public: `Transport` (`send()` and `close()`),
+  `PreparedRequest` and `prepare_request()` give another transport (on
+  `requests`, `httpx`, or a fake) the checks and body framing of syshttp's own.
+  `SYSHTTP_DEFAULT_TRANSPORT` (`module:attr` or `<file>.py:attr`, read under the
+  prefixes) names the transport of a client given none; a value that cannot be
+  used is `ConfigurationError`. `hooks.load_object()` is the loader it shares
+  with the `_PY` hooks.
+- `syshttp.exceptions`: `SysHTTPError` (the base of what goes wrong at run
+  time), `ConfigurationError` (a `ValueError`), `HookError` (a `RuntimeError`)
+  and `ResponseError` (a `ValueError`), exported from the root. A malformed
+  setting, a hook that cannot be loaded, a failing hook and a body that is not
+  JSON raise them; every one is still the `ValueError` or `RuntimeError` it
+  was, so existing handlers keep working. A caller's own mistake stays a plain
+  `ValueError` / `TypeError`.
+- Every public module declares `__all__` (`proxy` also lists its setting-name
+  constants, `PROXY` and `DEFAULT_AUTH_HEADER` among them).
+- `syshttp.env.HTTPEnv(prefixes=None, environ=None)`: every setting is a
+  variable with a full name -- syshttp's own carry `SYSHTTP_`
+  (`SYSHTTP_PROXY`, `SYSHTTP_HOME`, `SYSHTTP_HOOKS_<KEY>`,
+  `SYSHTTP_IMPORTPATCH`), conventional ones keep theirs (`HTTPS_PROXY`,
+  `NO_PROXY`, `HTTP_PROXY_AUTH`, `CA_BUNDLE`) -- read as `<PREFIX><NAME>` for
+  each prefix of `SYSHTTP_PREFIX` in turn, a `:`-separated list used
+  literally (default: one empty prefix, the names as written). The first
+  prefix that sets a variable wins, each variable on its own:
+  `SYSHTTP_PREFIX=MYTOOL_` reads only `MYTOOL_<NAME>`, `MYTOOL_:` falls back
+  to the unprefixed names. `find()` returns the variable found with its
+  value, for messages. Every function that reads a setting takes `env=`,
+  `new_session()` and the `fetch` `*_auto` helpers included.
+- `CA_BUNDLE` (under the prefixes) names the CA bundle a session's
+  `verify=True` uses; sessions no longer read requests' own
+  `REQUESTS_CA_BUNDLE` / `CURL_CA_BUNDLE`.
+- The system's proxy configuration is the last proxy source, decided for the
+  URL being requested: WinHTTP on Windows, CFNetwork on macOS, libproxy or the
+  desktop's settings elsewhere, PAC scripts and WPAD included (through
+  proxylib, a new dependency). It comes after `SYSHTTP_PROXY` and the
+  `*_PROXY` variables, after the `NO_PROXY` check, and is always spoken to as
+  `connect`. `SYSHTTP_SYSTEM_PROXY=0` turns it off. `proxy.plan()`,
+  `proxy_url()`, `resolve()` and `proxy_authorization()` take the request URL
+  (`url=` / `target=`). `proxy.configured_proxy_url()` gives the
+  environment's answer alone. The `pac` extra adds a JavaScript engine for PAC
+  scripts proxylib evaluates itself (Linux without libproxy).
+- `syshttp.autopatch`: `SYSHTTP_IMPORTPATCH=1` (or `:`-separated names:
+  `requests`, `urllib`, `httpx`, `aiohttp`; read under the prefixes like
+  every setting) patches those libraries as they are imported,
+  in any program of the environment, so requests without a proxy or TLS
+  setting of the caller's route by syshttp and verify with the system's
+  context. Through importpatch, a new dependency, and its entry points;
+  `patch()` / `unpatch()` do it from code.
+- The system's answer is a list (`PROXY a; PROXY b; DIRECT`): the first proxy
+  that accepts a connection is used (proxylib's `first_working_proxy`), and a
+  DIRECT reached first is direct. No reachable proxy and no DIRECT raises
+  `proxy.NoReachableProxyError` (a `ConnectionError`, exported from the
+  root); a session raises `requests.exceptions.ProxyError` for it.
+- `new_session(ssl_context=..., proxy_ssl_context=...)` (and the same on the
+  `fetch` `*_auto` helpers): a caller's `ssl.SSLContext` is used as given for
+  every https origin, or for an `https://` proxy. That covers mutual TLS,
+  ciphers and protocol versions. It cannot be combined with a `verify` other
+  than `True`.
+- `hooks.wrapper_environment()`: the `SYSHTTP_HOOK_*` variables a `_CURL`
+  wrapper run receives.
+- `jar.default_root()`: the per-user state directory used when
+  `SYSHTTP_HOME` is unset.
+- `syshttp.__version__`.
+- Hosts that share cookies: `SYSHTTP_COOKIE_HOSTS` (hosts split by `,`,
+  groups by `;`) or `new_session(cookie_hosts=...)` declares names that reach
+  one service. In a group, a cookie a member sets for itself or another
+  member belongs to the first host, every member's requests carry the
+  group's cookies, and any member can delete them; a `Domain` outside the
+  group is still judged on the host that sent it. `cookies.host_aliases()`
+  builds the mapping, which `set_cookie_specs`, `merge_set_cookie_headers`
+  and `host_only_policy` take as `aliases=`.
+- The shipped header and the settings page list every variable syshttp
+  reads under its own name (the proxy family, `REQUEST_METHOD`, the CA bundle
+  variables, the state-directory variables, importpatch's and proxylib's).
+
+### Changed
+
+- `syshttp.fetch` is a function, not a module: `fetch()` replaces the helpers
+  below. `_PY` hooks are called as `hook(client, method, url, kwargs)` with the
+  keyword arguments of `HTTPClient.request()`, and may return an
+  `HTTPResponse`; `auth.AuthProvider.ensure(client, url)` takes the client.
+  `CA_BUNDLE` is the bundle a client's `verify=True` uses. `cookies.py` keeps
+  the Netscape rows, `set_cookie_specs`, `cookie_applies` and `host_aliases`
+  only; the client keeps its cookies as those rows.
+- Routing is proxylib 2's (`proxylib>=2.0.2,<3`; 2.0.1 breaks pip's cached
+  requests). `proxy.proxy_map(proxy,
+  noproxy, proxy_user, *, env)` is the settings as one proxylib proxy map,
+  read at each lookup; `proxy.configured_proxy()` is `SYSHTTP_PROXY` as a
+  proxylib `Proxy`; `proxy.system_map()` is the system's configuration
+  (`proxylib.auto_proxy`). The `*_PROXY` variables are read per scheme
+  (lowercase first, httpoxy-safe), `NO_PROXY` takes CIDR entries, and curl's
+  `-x ""` is direct. `SYSHTTP_PROXY_AUTH` goes to `SYSHTTP_PROXY` only and
+  `HTTP_PROXY_AUTH` to the machine's proxies only.
+- A list from the system (`PROXY a; PROXY b; DIRECT`) is tried in order by the
+  session, httpx and aiohttp (proxylib's failover), replacing the probe of
+  the entry above; urllib takes the first reachable entry. No proxy
+  connecting and no DIRECT is the client's own connection error;
+  `NoReachableProxyError` is proxylib's.
+- The session's `ProxyAdapter` is proxylib's `ProxyMapAdapter` with the
+  system's TLS; `adapter.route(url)` returns the entries it will try.
+  `proxies=` given to `new_session` are requests' own, with no syshttp
+  credential added.
+- `syshttp.autopatch` routes through `proxylib.patch()` and patches TLS only;
+  requests' TLS is a pool hook on every `HTTPAdapter`. A caller's own
+  proxies and `trust_env = False` still win over syshttp (proxylib 2.0.2's
+  rule). aiohttp is not offered
+  URL-prefix gateways. New target `pip` (`pip._vendor.requests`, proxylib
+  2.0.1's `pip` target): pip's adapters route through the map unless pip is
+  given `--proxy` or `--no-proxy-env`; pip keeps its own TLS context.
+
+- The jar constructors (`FileCookieJar`, `FileTokenJar`) no longer create
+  their directory; it is created at the first write.
+
+- A session returns the last response when a status in `status_forcelist`
+  outlasts its retries, as plain requests does; it used to raise
+  `requests.exceptions.RetryError`, which the fetch helpers (`-> (status,
+  text)`) passed on. The `*_auto` helpers take `new_session`'s options as
+  `**session_options` (every keyword they had still works) and their
+  `timeout` may be a `(connect, read)` pair.
+- Every dependency's floor is its newest release that supports Python 3.9:
+  the `session` extra requires `requests>=2.32.5` and `urllib3>=2.6.3` (was
+  `requests>=2.25`), and `sslcontext>=2.1.0`. Below requests 2.32.3 a caller's
+  `ssl_context` was silently ignored, urllib3 1.26 raises a bare `ValueError`
+  for an https IP-literal host, and urllib3 up to 2.2 leaks the socket of a
+  failed TLS handshake through an https proxy. On Python 3.9, botocore pins `urllib3<1.27`, so `syshttp[session]`
+  cannot share an environment with it there.
+
+
+- The header says that jars, tokens, `_PY` hooks and `auth_provider` apply to
+  `session.request` and not to a bare `session.send()`, which gets the proxy
+  decision and TLS only.
+
+- `new_session()` no longer calls `urllib3.disable_warnings`, which silenced
+  `InsecureRequestWarning` for the whole process; with `verify=False` urllib3
+  warns as it does for any requests session. The undocumented
+  `syshttp.warnings` module is gone.
+
+### Removed
+
+- `syshttp.session` (`new_session()` and its `requests` adapter), the
+  `session` extra (and its `requests` and `urllib3` floors; `requests` stays a
+  development dependency for the tests of `syshttp.autopatch`), and the helpers
+  of the old `syshttp.fetch` module: `request_text`, `request_json`,
+  `request_with_reauth`, `request_text_auto` and `request_json_auto`. Their
+  replacements are `HTTPClient` and `fetch()`. A per-request `verify=` and
+  `cert=` are gone with them: build a client with `verify=` or an
+  `ssl_context` that holds the identity. `cookies.apply_to_session`,
+  `merge_set_cookie_headers` and `host_only_policy`, which only a `requests`
+  session used, are gone too.
+- `proxy.proxy_url`, `configured_proxy_url`, `system_proxy`,
+  `system_proxy_map`, `first_reachable`, `PROBE_MAX_AGE`, `PROBE_TIMEOUT`,
+  `resolve`, `proxy_authorization`, `configured_authorization`, `userinfo`,
+  `basic_authorization`, `strip_auth`, `redact`, `prefix_url`,
+  `should_bypass`, `bypassed_by`, `no_proxy_from_env`, `proxies_from_env`,
+  `plan` and `ProxyPlan`: `proxy_map()` and proxylib's `Proxy` replace them.
+
+### Changed (earlier)
+
+- The package stands alone as `syshttp`. It was previously the `httplib`
+  library of the dotagents `net` overlay, which shipped with a curl-compatible
+  command (`httplib.cli`, `python -m httplib`) that is now the `curlike`
+  package. Imports move from `httplib` to `syshttp`, and settings from the
+  dotagents names to the prefixed ones: `AGENTS_PROXY` → `SYSHTTP_PROXY`,
+  `AGENTS_PROXY_AUTH` → `SYSHTTP_PROXY_AUTH`, `AGENTS_PROXY_AUTH_HEADER` →
+  `SYSHTTP_PROXY_AUTH_HEADER`, `AGENTS_PROXY_TYPE` → `SYSHTTP_PROXY_TYPE`,
+  `AGENTS_HOME` → `SYSHTTP_HOME`, `NET_HOOKS_<KEY>` → `SYSHTTP_HOOKS_<KEY>`,
+  `NET_HOOK_*` → `SYSHTTP_HOOK_*`. A tool's own namespace is a prefix:
+  `SYSHTTP_PREFIX=AGENTS_` reads `AGENTS_SYSHTTP_PROXY`,
+  `AGENTS_SYSHTTP_HOOKS_<KEY>` and so on.
+- The system's TLS client by default: `tls.new_os_context()` (and so
+  `os_ssl_context()` and every session with `verify=True`) returns
+  `sslcontext.system_context()` (sslcontext 2 is a new dependency).
+  Certificates are verified by the operating system on Python 3.10+
+  (CryptoAPI on Windows, the Security framework on macOS, OpenSSL over the
+  system store elsewhere), by OpenSSL over the default store on 3.9, and a
+  server that asks for a client certificate gets one from the OS store,
+  chosen as a browser chooses. `new_os_context(client_certificates=False)`
+  offers none, for a caller loading its own. A `cafile` / `capath` still
+  replaces the store with a plain `ssl` context.
+- A session without caller `proxies` decides the proxy for every request and
+  every redirect hop, from the environment as it is then and the system's
+  answer for that URL. A direct decision is final: requests' `trust_env` cannot
+  re-add a proxy. `adapter.route(url)` shows the decision.
+- Without `SYSHTTP_HOME`, the jars live in the per-user state directory
+  instead of the dotagents store directory.
+- `proxy.resolve()` and `proxy.proxy_authorization()`: the keyword `env: bool`
+  is now `configured: bool`.
+- `hooks.hooks_from_env()`, `matching()`, `skipped()` and `call_py_hooks()`
+  take `env: HTTPEnv` (keyword-only) instead of a mapping `environ`.
+  `hooks.PREFIX`, `SKIP_ENV`, `URL_ENV`, `KEY_ENV` and `CURL_ENV` are
+  replaced by the setting names `HOOKS`, `HOOK_SKIP`, `HOOK_URL`, `HOOK_KEY`
+  and `HOOK_CURL`.
+- `proxy.AUTH_VARS`, `AUTH_HEADER_VAR` and `TYPE_VAR` are replaced by the
+  setting names `PROXY_AUTH`, `PROXY_AUTH_HEADER` and `PROXY_TYPE`.
+
+### Fixed
+
+- A by-host cookie file keeps a cookie its host set for a parent domain
+  (`Domain=example.com` from `www.example.com`); it was never saved.
+- The proxy credential reaches a proxy whose host is configured in upper
+  case. requests lower-cases the proxy URL it hands to `proxy_headers`, so the
+  credential used to be dropped and the proxy answered 407.
+- `Set-Cookie` is read as RFC 6265 section 5.2 reads it, not through
+  `http.cookies.SimpleCookie`: a value with a space or JSON is kept, an
+  unknown attribute (`Priority`, `Partitioned`) is no longer a cookie of its
+  own, `Max-Age` beats `Expires`, and a header with no `name=value` is
+  skipped. A `Domain` without a leading dot covers subdomains. A cookie with
+  no `Path` gets the directory of the request path
+  (`set_cookie_specs(..., request_path=)`).
+- A session holds one copy of each cookie. `merge_set_cookie_headers` no
+  longer re-sets what requests already stored (it used to add a second copy
+  with path `/` and a dotless domain); it applies only the deletions requests
+  misses, for redirect hops too.
+- A cookie set without `Domain` stays on its host: rows loaded from a jar and
+  cookies a server sets are no longer sent to subdomains
+  (`new_session` uses `cookies.host_only_policy()`).
+- A cookie for a single-label host (`localhost`, `wiki`) is loaded from its
+  jar file, and is saved under its own name instead of `localhost.local`.
+- `FileCookieJar` keeps `HttpOnly` and the include-subdomains flag.
+- `load_netscape` keeps a row whose value is empty, and an expiry written
+  with a non-ASCII digit is a session cookie instead of a `ValueError`.
+  `retry_after` returns `None` for such a value, and reads an HTTP date
+  written without a zone (`asctime`) as UTC.
+- A cookie expiry beyond 400 days is cut to 400 days.
+- A hook whose `_PY` / `_CURL` target is blank is ignored instead of failing
+  every request, and `HTTPEnv.family` strips values as `get` does.
+- Hook KEYs are compared without regard to case: `HOOK_SKIP=mykey` did not
+  suppress `MYKEY`, the form Windows holds. `Hook.key` and `skipped()` are
+  upper-case.
+- A `<file>.py:callable` hook's module is loaded once per process, not on
+  every request (its module-level state was reset each time), and two files
+  with one name no longer share a module name.
+- `request_text_auto` and `request_json_auto` retry a 408 by default, as
+  `new_session` does (their own list had dropped it), and close the session
+  they built instead of leaking its connection pool. The five fetch helpers
+  have docstrings.
+- `new_session(user_agent=...)` sets the User-Agent; the default
+  `python-requests/x` was sent whatever was given.
+- The guards that keep a hook or `auth_provider.ensure` from running again for
+  its own requests are per thread: while one thread was inside a hook, the
+  other threads' requests skipped hooks and `ensure`.
+- A request-level `verify=` (`False`, or a bundle) beside `ssl_context`, which
+  was silently ignored, raises `ValueError` as the same value does at session
+  level. `CA_BUNDLE` is not a request-level value, and a session with an
+  `ssl_context` does not consult it.
+- The import patch replaces requests 2.32.3's own default context (a certifi
+  bundle) in a pool, as it does for the later versions that leave it out.
+- Token and cookie files are replaced whole by a rename, so a reader never sees
+  an empty or half-written file and concurrent savers no longer truncate each
+  other's file.
+- `SYSHTTP_HOME=~/jars` is expanded instead of creating a directory named `~`.
+- Jar files are written with LF on Windows too, as curl writes them.
+- A session whose cookie jar cannot be read (an error while iterating
+  `session.cookies`) no longer saves an empty list over the host's cookies, and
+  writes a host's file only when its cookies changed instead of after every
+  response.
+
+### Security
+
+- The client closes six gaps found in review. A `Set-Cookie` with a control
+  character in it is ignored whole (RFC 6265bis 5.6), `load_netscape` ends a
+  line at a newline only (it ended one at `\x0b`, `\x0c`, `\x1c`-`\x1e` and
+  `\x85` too, so a value could become a whole row for another domain),
+  `save_netscape` writes no row with a control character or a tab in a field,
+  and a by-host jar file gives the client only the rows that cover its host or
+  group. A plain-http response can no longer set a Secure cookie, or set,
+  replace or delete one that is stored (RFC 6265bis 5.7; the loopback hosts
+  count as secure, as in curl). A redirect to another scheme, host or port
+  drops a caller's `Cookie` and `Proxy-Authorization` header with
+  `Authorization`. `HTTPTransport.send(stream=False)` and
+  `HTTPResponse.buffered()` hold a decoded reply to `MAX_REPLY_BYTES` (a
+  kilobyte of gzip decoded to tens of megabytes), and the too-large error names
+  the URL as scheme, host, port and path, without its query. An `https:` origin
+  is no longer sent through a plain `prefix+http` gateway, which would carry its
+  tokens and Secure cookies in clear text: the entry is skipped, and with
+  nothing else left the request raises `proxylib.UnsupportedProxyError`.
+- A `Set-Cookie` can no longer name a domain its host does not own. Any
+  host could set or delete another host's cookie (`Domain=bank.example` from
+  `evil.example`) or one for a top level domain; such a header is now skipped
+  on a set and on a deletion, in the session, in `FileCookieJar` and in
+  `set_cookie_specs` (which curlike's `-c` uses). A public suffix is
+  recognised without the Public Suffix List (a name with no dot, or a
+  `co.uk`-style registry).
+- Token and cookie files are created `0600`, and the directories this library
+  creates `0700`, instead of world-readable under a usual umask.
+- A client certificate passed as `cert=` is no longer loaded into the shared OS
+  context (or into the caller's `ssl_context`), where every later session, and
+  every other user of that context, presented it too. It gets a context of the
+  session's own; `cert=` beside `ssl_context` raises `ValueError`.
+- A URL-prefix gateway is spoken to with `proxy_ssl_context` (or the system's
+  verifier), no longer with the `ssl_context` and client certificate meant for
+  the origin.
+- A token, or a proxy credential, containing CR, LF or NUL raises a
+  `ValueError` that names the jar key or variable instead of requests'
+  `InvalidHeader` carrying the whole secret.
+- No setting can be chosen by a CGI client unless the program reads the
+  unprefixed names: syshttp's own all start `SYSHTTP_`, which a request
+  header never becomes, and a CGI program sets a prefix list without the
+  empty entry so that `HTTP_PROXY` and `HTTP_PROXY_AUTH` are not read.
+- A failing hook's message names its URL as scheme, host, port and path, no
+  longer with the userinfo, query and fragment (`user:pass@`,
+  `?access_token=`).
+
+[Unreleased]: https://github.com/jose-pr/syshttp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jose-pr/syshttp/releases/tag/v0.1.0

syshttp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose A.
+
+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.

syshttp-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.5
+Name: syshttp
+Version: 0.1.0
+Summary: HTTP plumbing that follows the system: the system proxy (PAC, WPAD) and the OS certificate verifier by default, proxy credentials and prefix gateways, Netscape cookie jars, OS trust-store TLS, URL hooks, and an HTTP client on the standard library
+Project-URL: Homepage, https://github.com/jose-pr/syshttp
+Project-URL: Documentation, https://jose-pr.github.io/syshttp/
+Project-URL: Issues, https://github.com/jose-pr/syshttp/issues
+Author-email: jose-pr <jose-pr@coqui.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: importpatch<0.3,>=0.2.1
+Requires-Dist: proxylib<3,>=2.0.2
+Requires-Dist: sslcontext<3,>=2.1.0
+Provides-Extra: dev
+Requires-Dist: aiohttp; extra == 'dev'
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: mypy<2; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: requests; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: pac
+Requires-Dist: proxylib[pac]<3,>=2.0.2; extra == 'pac'
+Description-Content-Type: text/markdown
+
+# syshttp
+
+[![Version](https://img.shields.io/pypi/v/syshttp.svg)](https://pypi.org/project/syshttp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/syshttp.svg)](https://pypi.org/project/syshttp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/syshttp/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/syshttp/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/syshttp/test.yml)](https://github.com/jose-pr/syshttp/actions/workflows/test.yml)
+
+**HTTP plumbing that behaves the same in every client you build on it**:
+which proxy to use, with which credential, for which hosts; how a prefix
+gateway is spoken to; which cookies and tokens go with which origin; and TLS
+through the operating system's own certificate verifier. By default it
+routes the way the system does: the system's proxy configuration, PAC scripts
+and WPAD included, unless a proxy variable says otherwise. An HTTP client on the
+standard library puts all of them together; `requests` is needed by none of
+it. Documentation: <https://jose-pr.github.io/syshttp/>.
+
+## Features
+
+- **Routing is [proxylib](https://pypi.org/project/proxylib/)'s** —
+  `proxy.proxy_map()` turns the settings below into one proxylib proxy map,
+  and proxylib's client integrations send through it.
+- **The system's proxy, by default** — with no proxy variable set, the
+  system's configuration decides per URL: WinHTTP on Windows, CFNetwork on
+  macOS, libproxy or the desktop's settings elsewhere, PAC and WPAD included.
+  A list (`PROXY a; PROXY b; DIRECT`) is tried in order, the next entry when
+  one does not connect; with no proxy connecting and no DIRECT the request
+  fails rather than going direct.
+- **Proxies with credentials** — a proxy URL from `SYSHTTP_PROXY`, else the
+  usual `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` for the request's scheme.
+  The credential is a header value sent verbatim to that proxy only, so any
+  scheme works (`Basic`, `Bearer`, `Negotiate`). `NO_PROXY` is honoured
+  (CIDR included), and every redirect hop is decided again.
+- **Prefix gateways** — `SYSHTTP_PROXY_TYPE=prefix:/fetch/` sends
+  `GET https://api.example.com/x` to `<proxy>/fetch/https://api.example.com/x`
+  (the client, requests, httpx and urllib; the client sends an `https:` origin
+  through an `https` gateway only). Responses, redirects and cookies still use
+  the caller's URL.
+- **Prefixes of a tool's own** — `SYSHTTP_PREFIX=MYTOOL_` makes the package
+  read `MYTOOL_HTTPS_PROXY`, `MYTOOL_SYSHTTP_HOME` and so on instead of the
+  defaults; `MYTOOL_:` falls back to them, variable by variable. An
+  `HTTPEnv("MYTOOL_")` object keeps one configuration apart from another in
+  the same process.
+- **Cookie and token jars** — Netscape cookie files with curl's matching
+  rules, plus per-host token files. Both are chosen by the origin's host,
+  never by the proxy's or the gateway's.
+- **URL hooks** — `SYSHTTP_HOOKS_<KEY>=<regex>` plus `_PY=module:callable`
+  runs your code before matching requests: a login, a signature, a canned
+  response.
+- **The system's TLS client, or your own TLS context** — by default
+  [sslcontext](https://pypi.org/project/sslcontext/)'s system context: the
+  operating system verifies certificates (CryptoAPI, the Security framework),
+  with no `certifi` bundle involved, and a server that asks for a client
+  certificate gets one from the OS store (smart cards included), chosen as a
+  browser chooses. Or `HTTPClient(ssl_context=...)` for a given identity, a
+  cipher list or a pinned protocol version.
+- **An HTTP client on the standard library** — `HTTPClient` and `fetch()`:
+  retry with backoff, redirects that keep a credential with its origin, and
+  all of the above, on `http.client` and `ssl` alone. Its transport is
+  replaceable: any object with `send()` (a `requests` or `httpx` one, a fake
+  in a test), chosen per client or by `SYSHTTP_DEFAULT_TRANSPORT`.
+- **Other programs' clients, patched on import** — `SYSHTTP_IMPORTPATCH=1`
+  (or `requests:urllib:httpx:aiohttp:pip`) makes those libraries route and
+  verify the same way in any program of the environment, through
+  [importpatch](https://pypi.org/project/importpatch/); what a caller sets
+  itself still wins.
+
+## Installation
+
+```bash
+pip install syshttp
+```
+
+| Extra | Adds | Needed for |
+| --- | --- | --- |
+| `pac` | a JavaScript engine for proxylib | PAC scripts proxylib evaluates itself (Linux without libproxy) |
+
+syshttp depends on proxylib (the system proxy), sslcontext (the system's
+TLS client: the OS verifier through truststore on Python 3.10+, OpenSSL over
+the default store on 3.9) and importpatch (its `.pth` hooks imports at
+interpreter start; nothing is patched unless `SYSHTTP_IMPORTPATCH` says so).
+
+## Quick start
+
+Ask where a request would go, the way every client here does:
+
+```python
+import proxylib
+from syshttp import proxy
+
+for entry in proxylib.lookup(proxy.proxy_map(), "https://api.example.com/"):
+    print("DIRECT" if entry is None else entry.url)   # tried in this order
+```
+
+One request, routed and verified the way the system does (no extra to install):
+
+```python
+from syshttp import fetch
+
+response = fetch("https://api.example.com/thing")
+print(response.status, response.json())
+```
+
+A client with file-backed cookies and tokens, kept across requests:
+
+```python
+from syshttp.client import HTTPClient
+
+with HTTPClient(cookies=True, tokens=True) as client:
+    response = client.request("GET", "https://api.example.com/thing")
+```
+
+A separate configuration, isolated from the process environment:
+
+```python
+from syshttp import HTTPEnv, fetch
+
+env = HTTPEnv("MYTOOL_", environ={"MYTOOL_SYSHTTP_PROXY": "http://proxy.internal:3128"})
+response = fetch("https://api.example.com/thing", env=env)
+```
+
+## API overview
+
+| Module | Purpose |
+| --- | --- |
+| `syshttp.env` | `HTTPEnv`: the prefixes and mapping every setting is read from |
+| `syshttp.proxy` | `proxy_map()`: the settings as one proxylib proxy map |
+| `syshttp.client` | `HTTPClient` and `fetch()`: the HTTP client, its transport protocol and response |
+| `syshttp.jar` | file and memory cookie/token jars |
+| `syshttp.cookies` | Netscape cookie files and curl's cookie rules |
+| `syshttp.hooks` | URL hooks declared in the environment |
+| `syshttp.tls` | the OS verifier as an `SSLContext` |
+| `syshttp.autopatch` | requests, urllib, httpx, aiohttp and pip patched on import |
+| `syshttp.retry` | the transient statuses, `Retry-After` |
+
+## Settings
+
+Every setting is read as `<PREFIX><NAME>` for each prefix of
+`SYSHTTP_PREFIX` (`:`-separated; default none, the names as written). The
+full list is on the docs site:
+<https://jose-pr.github.io/syshttp/settings/>.
+
+| Variable | Sets |
+| --- | --- |
+| `SYSHTTP_PREFIX` | the prefixes every other setting is read under |
+| `SYSHTTP_PROXY` | the proxy URL; else `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, else the system's |
+| `SYSHTTP_SYSTEM_PROXY` | `0` to stop consulting the system's proxy configuration |
+| `SYSHTTP_PROXY_AUTH` | the proxy credential, sent verbatim; else `HTTP_PROXY_AUTH` |
+| `SYSHTTP_PROXY_AUTH_HEADER` | the header it is sent in (default `Proxy-Authorization`) |
+| `SYSHTTP_PROXY_TYPE` | `connect` (default) or `prefix[:/endpoint]` |
+| `SYSHTTP_HOME` | the jar directory (default: the per-user state directory) |
+| `SYSHTTP_IMPORTPATCH` | `1`, or `:`-separated names: the client libraries patched on import |
+| `SYSHTTP_HOOKS_<KEY>` | a URL hook's pattern, with `_PY` / `_CURL` targets |
+| `SYSHTTP_DEFAULT_TRANSPORT` | `module:attr` or `<file>.py:attr`: the transport of a client given none (it names code to import) |
+| `CA_BUNDLE` | the CA bundle a client verifies with (default: the OS verifier) |
+
+## Development
+
+```bash
+dotagents pyvenv            # or any Python 3.9+ virtual environment
+.pyvenv/<tag>/Scripts/python -m pip install -e ".[dev]"
+.pyvenv/<tag>/Scripts/python -m pytest -q
+```
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](https://github.com/jose-pr/syshttp/blob/main/CHANGELOG.md).
+Pushing a tag matching `v*` triggers the release workflow: test gate → build
+(checking the tag names the version built) → a strict docs build as a gate →
+GitHub release → publish. The release workflow never deploys the docs site
+itself: for a final release its last job dispatches the docs workflow at the
+tag, which owns every Pages deploy.
+
+## License
+
+MIT — see [LICENSE](https://github.com/jose-pr/syshttp/blob/main/LICENSE).