unixsr 0.0.1__tar.gz

unixsr-0.0.1/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+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.

unixsr-0.0.1/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: unixsr
+Version: 0.0.1
+Summary: UNIXSR: Unix Style Request — Axios with a Unix vocabulary HTTP client
+Author: Unix Style Request Project
+License: MIT
+Keywords: http,client,axios,unix,unixsr,usr
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.24
+Dynamic: license-file
+
+# usr
+
+USR: Unix Style Request — Axios with a Unix vocabulary HTTP client.
+
+## Install
+
+```sh
+pip install usr
+```
+
+## Quick start
+
+```python
+from usr import *
+
+res = cat("https://api.site.com/users")
+print(res.status, res.data)
+
+touch("https://api.site.com/users", {"name": "Ada"})
+sed("https://api.site.com/users/42", {"active": False})
+rm("https://api.site.com/users/42")
+```
+
+## Flags
+
+Structured keyword form or a curl-like command-line string:
+
+```python
+cat("https://api.site.com/me", H="Authorization: Bearer TOKEN", m=5)
+# or
+cat("-H 'Authorization: Bearer TOKEN' -m 5 https://api.site.com/me")
+```
+
+## Pipes (real ``|`` operator)
+
+```python
+names = cat("https://api.site.com/users") | grep(active=True) | cut("name") | head(5)
+```
+
+## Scoped client
+
+```python
+api = cd("https://api.site.com", H="Authorization: Bearer TOKEN")
+me = api.cat("/me")
+```
+
+## Async
+
+```python
+from usr import aio
+
+res = await aio.cat("https://api.site.com/users")
+```

unixsr-0.0.1/README.md

@@ -0,0 +1,53 @@
+# usr
+
+USR: Unix Style Request — Axios with a Unix vocabulary HTTP client.
+
+## Install
+
+```sh
+pip install usr
+```
+
+## Quick start
+
+```python
+from usr import *
+
+res = cat("https://api.site.com/users")
+print(res.status, res.data)
+
+touch("https://api.site.com/users", {"name": "Ada"})
+sed("https://api.site.com/users/42", {"active": False})
+rm("https://api.site.com/users/42")
+```
+
+## Flags
+
+Structured keyword form or a curl-like command-line string:
+
+```python
+cat("https://api.site.com/me", H="Authorization: Bearer TOKEN", m=5)
+# or
+cat("-H 'Authorization: Bearer TOKEN' -m 5 https://api.site.com/me")
+```
+
+## Pipes (real ``|`` operator)
+
+```python
+names = cat("https://api.site.com/users") | grep(active=True) | cut("name") | head(5)
+```
+
+## Scoped client
+
+```python
+api = cd("https://api.site.com", H="Authorization: Bearer TOKEN")
+me = api.cat("/me")
+```
+
+## Async
+
+```python
+from usr import aio
+
+res = await aio.cat("https://api.site.com/users")
+```

unixsr-0.0.1/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unixsr"
+version = "0.0.1"
+description = "UNIXSR: Unix Style Request — Axios with a Unix vocabulary HTTP client"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Unix Style Request Project"}]
+keywords = ["http", "client", "axios", "unix", "unixsr", "usr"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = ["httpx>=0.24,<1"]
+
+[project.scripts]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["unixsr*", "usr*"]

unixsr-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unixsr-0.0.1/unixsr/__init__.py

@@ -0,0 +1,67 @@
+"""USR: Unix Style Request — Axios with a Unix vocabulary HTTP client.
+
+Synchronous by default. Use ``from usr import *`` safely (explicit ``__all__``;
+no Python builtins are shadowed).
+"""
+
+from __future__ import annotations
+
+from ._client import Response, UsrClient, cd, defaults, create_usr
+from ._error import UsrError
+from ._flags import normalize_flags, parse_flags_string, parse_flag_string
+from ._pipe import PipeError, cut, grep, head, pipeable, sort, tail, tee, uniq, wc, xargs
+from . import _async as aio
+
+_client: UsrClient = create_usr()
+
+cat = _client.cat
+touch = _client.touch
+mv = _client.mv
+sed = _client.sed
+rm = _client.rm
+stat = _client.stat
+man = _client.man
+trap = _client.trap
+untrap = _client.untrap
+
+
+def request(config: dict) -> Response:
+    return _client.request(config)
+
+
+__all__ = [
+    "cat",
+    "touch",
+    "mv",
+    "sed",
+    "rm",
+    "stat",
+    "man",
+    "request",
+    "trap",
+    "untrap",
+    "grep",
+    "head",
+    "tail",
+    "sort",
+    "uniq",
+    "cut",
+    "wc",
+    "tee",
+    "xargs",
+    "cd",
+    "defaults",
+    "UsrError",
+    "parse_flags_string",
+    "parse_flag_string",
+    "normalize_flags",
+    "pipeable",
+    "PipeError",
+    "Response",
+    "AsyncResponse",
+    "aio",
+    "create_usr",
+]
+
+# Re-export async response type name for convenience.
+from ._async import AsyncResponse  # noqa: E402

unixsr-0.0.1/unixsr/_adapter.py

@@ -0,0 +1,104 @@
+"""HTTP transport adapter backed by httpx (synchronous)."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from ._config import append_query, normalize_headers, resolve_url, serialize_body, validate_status_default
+from ._error import (
+    UsrError,
+    bad_request_error,
+    bad_response_error,
+    canceled_error,
+    invalid_url_error,
+    network_error,
+    timeout_error,
+    too_many_redirects_error,
+)
+
+REDIRECT_STATUS = {301, 302, 303, 307, 308}
+
+
+def _headers_obj(headers: httpx.Headers) -> dict:
+    return dict(headers)
+
+
+def dispatch(config: dict) -> dict:
+    url = append_query(resolve_url(config.get("base_url"), str(config["url"])), config.get("params"))
+    headers = normalize_headers({"accept": "application/json", **(config.get("headers") or {})})
+    body, headers = serialize_body(config.get("data"), headers)
+
+    timeout = config.get("timeout", 0)
+    httpx_timeout = httpx.Timeout(timeout) if timeout else None
+
+    max_redirects = config.get("max_redirects")
+    follow = max_redirects is None
+
+    try:
+        with httpx.Client(timeout=httpx_timeout, follow_redirects=follow, max_redirects=max_redirects or 20) as client:
+            response = client.request(config["method"], url, headers=headers, content=body)
+    except httpx.TimeoutException as exc:
+        raise timeout_error(config) from exc
+    except httpx.NetworkError as exc:
+        raise network_error(str(exc), config) from exc
+    except httpx.TooManyRedirects as exc:
+        raise too_many_redirects_error(config) from exc
+    except httpx.InvalidURL as exc:
+        raise invalid_url_error(str(exc), config) from exc
+    except httpx.RequestError as exc:
+        raise network_error(str(exc), config) from exc
+
+    if not follow and response.status_code in REDIRECT_STATUS:
+        raise too_many_redirects_error(
+            config,
+            response=_response_dict(response, config),
+            status=response.status_code,
+        )
+
+    status = response.status_code
+    validate_status = config.get("validate_status") or validate_status_default
+    content_type = response.headers.get("content-type", "")
+    is_json = "application/json" in content_type
+    text = response.text
+
+    try:
+        data = _json_loads(text) if is_json else text
+    except Exception:
+        data = text
+
+    res = {
+        "data": data,
+        "status": status,
+        "statusText": response.reason_phrase,
+        "headers": _headers_obj(response.headers),
+        "config": config,
+        "request": response,
+    }
+
+    if not validate_status(status):
+        raise bad_request_error(f"Request failed with status {status}", config, res, status=status)
+
+    return res
+
+
+def _json_loads(text: str):
+    import json as _json
+
+    return _json.loads(text)
+
+
+def _response_dict(response: httpx.Response, config: dict) -> dict:
+    try:
+        data = response.json()
+    except Exception:
+        data = response.text
+    return {
+        "data": data,
+        "status": response.status_code,
+        "statusText": response.reason_phrase,
+        "headers": _headers_obj(response.headers),
+        "config": config,
+        "request": response,
+    }

unixsr-0.0.1/unixsr/_async.py

@@ -0,0 +1,180 @@
+"""Async companion namespace for USR (httpx.AsyncClient)."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+import httpx
+
+from ._config import append_query, normalize_headers, resolve_url, serialize_body, validate_status_default
+from ._error import (
+    UsrError,
+    bad_request_error,
+    canceled_error,
+    invalid_url_error,
+    network_error,
+    timeout_error,
+    too_many_redirects_error,
+)
+from ._pipe import PipeError, Pipeable
+from ._request import NO_BODY_METHODS, METHOD_BY_COMMAND
+
+
+class AsyncResponse:
+    __slots__ = ("_data", "status", "status_text", "headers", "config", "request")
+
+    def __init__(self, raw: dict) -> None:
+        self._data = raw["data"]
+        self.status = raw["status"]
+        self.status_text = raw.get("statusText", "")
+        self.headers = raw.get("headers", {})
+        self.config = raw.get("config", {})
+        self.request = raw.get("request")
+
+    @property
+    def data(self) -> Any:
+        return self._data
+
+    def __or__(self, stage):
+        return Pipeable(stage(self._data))
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return f"AsyncResponse(status={self.status}, data={self._data!r})"
+
+
+async def _adispatch(config: dict) -> dict:
+    url = append_query(resolve_url(config.get("base_url"), str(config["url"])), config.get("params"))
+    headers = normalize_headers({"accept": "application/json", **(config.get("headers") or {})})
+    body, headers = serialize_body(config.get("data"), headers)
+
+    timeout = config.get("timeout", 0)
+    httpx_timeout = httpx.Timeout(timeout) if timeout else None
+    max_redirects = config.get("max_redirects")
+    follow = max_redirects is None
+
+    async with httpx.AsyncClient(timeout=httpx_timeout, follow_redirects=follow, max_redirects=max_redirects or 20) as client:
+        try:
+            response = await client.request(config["method"], url, headers=headers, content=body)
+        except httpx.TimeoutException as exc:
+            raise timeout_error(config) from exc
+        except httpx.NetworkError as exc:
+            raise network_error(str(exc), config) from exc
+        except httpx.TooManyRedirects as exc:
+            raise too_many_redirects_error(config) from exc
+        except httpx.InvalidURL as exc:
+            raise invalid_url_error(str(exc), config) from exc
+        except httpx.RequestError as exc:
+            raise network_error(str(exc), config) from exc
+
+    status = response.status_code
+    validate_status = config.get("validate_status") or validate_status_default
+    content_type = response.headers.get("content-type", "")
+    is_json = "application/json" in content_type
+    text = response.text
+    try:
+        import json as _json
+
+        data = _json.loads(text) if is_json else text
+    except Exception:
+        data = text
+
+    res = {
+        "data": data,
+        "status": status,
+        "statusText": response.reason_phrase,
+        "headers": dict(response.headers),
+        "config": config,
+        "request": response,
+    }
+
+    if not validate_status(status):
+        raise bad_request_error(f"Request failed with status {status}", config, res, status=status)
+    return res
+
+
+class AsyncUsrClient:
+    def __init__(self, base_config: Optional[dict] = None) -> None:
+        self.defaults: dict = dict(base_config or {})
+        self._traps: list = []
+
+    async def cat(self, url: str, options: Optional[dict] = None) -> AsyncResponse:
+        return await self._call("cat", url, None, options)
+
+    async def touch(self, url: str, data: Any = None, options: Optional[dict] = None) -> AsyncResponse:
+        return await self._call("touch", url, data, options)
+
+    async def mv(self, url: str, data: Any = None, options: Optional[dict] = None) -> AsyncResponse:
+        return await self._call("mv", url, data, options)
+
+    async def sed(self, url: str, data: Any = None, options: Optional[dict] = None) -> AsyncResponse:
+        return await self._call("sed", url, data, options)
+
+    async def rm(self, url: str, options: Optional[dict] = None) -> AsyncResponse:
+        return await self._call("rm", url, None, options)
+
+    async def stat(self, url: str, options: Optional[dict] = None) -> AsyncResponse:
+        return await self._call("stat", url, None, options)
+
+    async def man(self, url: str, options: Optional[dict] = None) -> AsyncResponse:
+        return await self._call("man", url, None, options)
+
+    async def _call(self, method: str, url: str, data: Any, options: Optional[dict]) -> AsyncResponse:
+        from ._config import merge_config
+
+        base = merge_config(self.defaults, options or {})
+        cfg = dict(base)
+        cfg["url"] = url
+        cfg["method"] = METHOD_BY_COMMAND[method]
+        if data is not None and method not in NO_BODY_METHODS:
+            cfg["data"] = data
+        cfg.setdefault("validate_status", validate_status_default)
+
+        def run_request_traps(c):
+            for t in self._traps:
+                if t["kind"] != "request":
+                    continue
+                if t.get("runWhen") and not t["runWhen"](c):
+                    continue
+                out = t["fn"](c)
+                if out is not None:
+                    c = out
+            return c
+
+        def run_response_traps(r):
+            for t in self._traps:
+                if t["kind"] != "response":
+                    continue
+                out = t["fn"](r)
+                if out is not None:
+                    r = out
+            return r
+
+        cfg = run_request_traps(cfg)
+        raw = await _adispatch(cfg)
+        raw = run_response_traps(raw)
+        return AsyncResponse(raw)
+
+    def trap(self, kind: str, fn: Callable, options: Optional[dict] = None) -> dict:
+        entry = {"kind": kind, "fn": fn, "runWhen": (options or {}).get("runWhen")}
+        self._traps.append(entry)
+        return {"eject": lambda: self._remove(entry)}
+
+    def untrap(self, handle: dict) -> None:
+        handle["eject"]()
+
+    def _remove(self, entry: dict) -> None:
+        if entry in self._traps:
+            self._traps.remove(entry)
+
+    def cd(self, base_url: str, options: Optional[dict] = None) -> "AsyncUsrClient":
+        from ._config import merge_config
+
+        merged = merge_config(self.defaults, {**dict(options or {}), "base_url": base_url})
+        client = AsyncUsrClient(merged)
+        client._traps = list(self._traps)
+        return client
+
+
+async def cd(base_url: str, options: Optional[dict] = None) -> AsyncUsrClient:
+    client = AsyncUsrClient({**dict(options or {}), "base_url": base_url})
+    return client.cd(base_url, options)

unixsr-0.0.1/unixsr/_client.py

@@ -0,0 +1,136 @@
+"""USR client: commands, scoped clients, defaults, and traps."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from ._adapter import dispatch
+from ._config import merge_config, validate_status_default
+from ._error import UsrError
+from ._pipe import PipeError, Pipeable, pipeable
+from ._request import NO_BODY_METHODS, METHOD_BY_COMMAND, request as raw_request
+
+
+class Response:
+    __slots__ = ("_data", "status", "status_text", "headers", "config", "request")
+
+    def __init__(self, raw: dict) -> None:
+        self._data = raw["data"]
+        self.status = raw["status"]
+        self.status_text = raw.get("statusText", "")
+        self.headers = raw.get("headers", {})
+        self.config = raw.get("config", {})
+        self.request = raw.get("request")
+
+    @property
+    def data(self) -> Any:
+        return self._data
+
+    def __or__(self, stage):
+        return Pipeable(stage(self._data))
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return f"Response(status={self.status}, data={self._data!r})"
+
+
+class UsrClient:
+    def __init__(self, base_config: Optional[dict] = None) -> None:
+        self.defaults: dict = dict(base_config or {})
+        self._traps: list = []
+
+    def _run_request_traps(self, config: dict) -> dict:
+        result = config
+        for t in self._traps:
+            if t["kind"] != "request":
+                continue
+            if t.get("runWhen") and not t["runWhen"](result):
+                continue
+            out = t["fn"](result)
+            if out is not None:
+                result = out
+        return result
+
+    def _run_response_traps(self, raw: dict) -> dict:
+        result = raw
+        for t in self._traps:
+            if t["kind"] != "response":
+                continue
+            out = t["fn"](result)
+            if out is not None:
+                result = out
+        return result
+
+    # -- commands --
+    def cat(self, url: str, options: Optional[dict] = None) -> Response:
+        return self._call("cat", url, None, options)
+
+    def touch(self, url: str, data: Any = None, options: Optional[dict] = None) -> Response:
+        return self._call("touch", url, data, options)
+
+    def mv(self, url: str, data: Any = None, options: Optional[dict] = None) -> Response:
+        return self._call("mv", url, data, options)
+
+    def sed(self, url: str, data: Any = None, options: Optional[dict] = None) -> Response:
+        return self._call("sed", url, data, options)
+
+    def rm(self, url: str, options: Optional[dict] = None) -> Response:
+        return self._call("rm", url, None, options)
+
+    def stat(self, url: str, options: Optional[dict] = None) -> Response:
+        return self._call("stat", url, None, options)
+
+    def man(self, url: str, options: Optional[dict] = None) -> Response:
+        return self._call("man", url, None, options)
+
+    def request(self, config: dict) -> Response:
+        merged = merge_config(self.defaults, config)
+        merged.setdefault("validate_status", validate_status_default)
+        merged = self._run_request_traps(merged)
+        raw = raw_request(merged)
+        raw = self._run_response_traps(raw)
+        return Response(raw)
+
+    def _call(self, method: str, url: str, data: Any, options: Optional[dict]) -> Response:
+        base = merge_config(self.defaults, options or {})
+        cfg = dict(base)
+        cfg["url"] = url
+        cfg["method"] = METHOD_BY_COMMAND[method]
+        if data is not None and method not in NO_BODY_METHODS:
+            cfg["data"] = data
+        cfg.setdefault("validate_status", validate_status_default)
+        cfg = self._run_request_traps(cfg)
+        raw = dispatch(cfg)
+        raw = self._run_response_traps(raw)
+        return Response(raw)
+
+    # -- traps --
+    def trap(self, kind: str, fn: Callable, options: Optional[dict] = None) -> dict:
+        entry = {"kind": kind, "fn": fn, "runWhen": (options or {}).get("runWhen")}
+        self._traps.append(entry)
+        return {"eject": lambda: self._remove(entry)}
+
+    def untrap(self, handle: dict) -> None:
+        handle["eject"]()
+
+    def _remove(self, entry: dict) -> None:
+        if entry in self._traps:
+            self._traps.remove(entry)
+
+    # -- scoped client --
+    def cd(self, base_url: str, options: Optional[dict] = None) -> "UsrClient":
+        merged = merge_config(self.defaults, {**dict(options or {}), "base_url": base_url})
+        client = UsrClient(merged)
+        client._traps = list(self._traps)
+        return client
+
+
+def cd(base_url: str, options: Optional[dict] = None) -> UsrClient:
+    client = UsrClient({**dict(options or {}), "base_url": base_url})
+    return client.cd(base_url, options)
+
+
+defaults: dict = {}
+
+
+def create_usr() -> UsrClient:
+    return UsrClient()