nonecap 0.1.0__tar.gz

nonecap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy
+      - run: pytest
+
+  publish:
+    # Tag pushes only (v0.1.0, v1.2.3, ...): build and publish to PyPI via
+    # trusted publishing (OIDC) — no token stored anywhere. One-time setup on
+    # PyPI: add this repo + workflow + the `pypi` environment as a (pending)
+    # trusted publisher for the `nonecap` project.
+    needs: test
+    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Verify tag matches package version
+        run: |
+          want="v$(python -c "import re;print(re.search(r'\"([^\"]+)\"', open('src/nonecap/_version.py').read()).group(1))")"
+          if [ "$want" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match _version.py ($want). Bump the version or retag."
+            exit 1
+          fi
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

nonecap-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.DS_Store
+.idea/
+.vscode/

nonecap-0.1.0/LICENSE

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

nonecap-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: nonecap
+Version: 0.1.0
+Summary: Official Python client for the NoneCap hCaptcha solving API.
+Project-URL: Homepage, https://nonecap.com
+Project-URL: Documentation, https://nonecap.com/api-reference
+Project-URL: Repository, https://github.com/nonecap/nonecap-py
+Project-URL: Issues, https://github.com/nonecap/nonecap-py/issues
+Author: Lunium
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,captcha,captcha-solver,hcaptcha,hcaptcha-solver,nonecap,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<h1 align="center">nonecap</h1>
+
+<p align="center">
+  <a href="https://github.com/nonecap/nonecap-py/actions/workflows/ci.yml"><img src="https://github.com/nonecap/nonecap-py/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/nonecap/"><img src="https://img.shields.io/pypi/v/nonecap.svg" alt="PyPI"></a>
+  <a href="https://pypi.org/project/nonecap/"><img src="https://img.shields.io/pypi/pyversions/nonecap.svg" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">Official Python client for the <a href="https://nonecap.com">NoneCap</a> hCaptcha solving API.</p>
+
+Submit a captcha, get back a token. The client handles the polling, the timeouts, and the error cases so you don't write the request loop yourself. Sync and async, fully typed.
+
+## Install
+
+```sh
+pip install nonecap
+```
+
+Python 3.9+. The only dependency is [httpx](https://www.python-httpx.org/).
+
+## Quick start
+
+Grab an API key from [dashboard.nonecap.com](https://dashboard.nonecap.com), then:
+
+```python
+from nonecap import NoneCap
+
+nc = NoneCap(api_key="nc_live_...")
+
+solve = nc.solve(
+    type="hcaptcha",
+    sitekey="10000000-ffff-ffff-ffff-000000000001",
+    url="https://example.com/login",
+)
+
+print(solve.token)  # the hCaptcha token, ready to submit
+```
+
+`solve()` submits the captcha and waits until it's done, using the API's long-poll so you aren't hammering it with requests. It returns the solved solve, or raises if the solve fails or your timeout runs out.
+
+## Async
+
+Same surface, `await`ed. Use it as an async context manager so the connection pool gets cleaned up:
+
+```python
+import asyncio
+from nonecap import AsyncNoneCap
+
+async def main() -> None:
+    async with AsyncNoneCap(api_key="nc_live_...") as nc:
+        solve = await nc.solve(type="hcaptcha", sitekey="...", url="https://example.com")
+        print(solve.token)
+
+asyncio.run(main())
+```
+
+## Handling failures
+
+Every error this library raises extends `NoneCapError`, so you can catch the whole family or pick out the one you care about.
+
+```python
+from nonecap import (
+    NoneCap,
+    SolveFailedError,
+    InsufficientCreditsError,
+    RateLimitError,
+)
+
+try:
+    solve = nc.solve(type="hcaptcha", sitekey=sitekey, url=url)
+except SolveFailedError as err:
+    print("Could not solve it:", err.solve.error.code if err.solve.error else "?")
+except InsufficientCreditsError:
+    print("Out of credits. Top up at dashboard.nonecap.com")
+except RateLimitError:
+    print("Too many solves in flight, back off and retry")
+```
+
+The subclasses are `AuthenticationError` (401), `PermissionDeniedError` (403), `InsufficientCreditsError` (402), `ValidationError` (422/400, with a `param` naming the bad field), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429), `APIError` (5xx), `APIConnectionError` and `APITimeoutError` (the request never landed), and `SolveTimeoutError` (your `solve()` budget ran out). `SolveFailedError` carries the full `solve` so you can read the underlying error code and the timings.
+
+## Enterprise captchas
+
+For `hcaptcha_enterprise`, `rqdata` is required. The `@overload` signatures enforce that in mypy and pyright, so leaving it out fails your type check, and a runtime check backs it up before any network call:
+
+```python
+solve = nc.solve(
+    type="hcaptcha_enterprise",
+    sitekey=sitekey,
+    url=url,
+    rqdata="...",  # required for enterprise
+)
+```
+
+## Proxies
+
+Pass a proxy as a dict or a URL string. The solve runs through it, and the bytes are metered back on the solve.
+
+```python
+nc.solve(
+    type="hcaptcha",
+    sitekey=sitekey,
+    url=url,
+    proxy={"scheme": "http", "host": "1.2.3.4", "port": 8080, "username": "u", "password": "p"},
+    # or: proxy="http://u:p@1.2.3.4:8080"
+)
+```
+
+## Lower-level API
+
+`solve()` is the convenient path. When you want control over submission and polling, the resource methods map one to one to the REST API:
+
+```python
+# Submit without waiting: returns immediately with a pending solve
+pending = nc.solves.create(type="hcaptcha", sitekey=sitekey, url=url)
+
+# Submit and hold the connection up to 30s for it to finish
+maybe_done = nc.solves.create(type="hcaptcha", sitekey=sitekey, url=url, wait=30)
+
+# Poll one solve, long-polling up to 30s
+solve = nc.solves.retrieve(pending.id, wait=30)
+
+# Cancel a pending or in-flight solve
+nc.solves.cancel(pending.id)
+
+# List a page of solves
+page = nc.solves.list(limit=50, status="solved")
+
+# Or iterate every solve, newest first
+for s in nc.solves.list_all():
+    print(s.id, s.status)
+
+# Your account and credit balance
+me = nc.me()
+print(me.credits_balance)
+```
+
+On `AsyncNoneCap` the same methods are coroutines, and `list_all()` is an async iterator (`async for s in nc.solves.list_all()`).
+
+## Configuration
+
+```python
+NoneCap(
+    api_key="nc_live_...",              # required
+    base_url="https://api.nonecap.com", # override if you need to
+    timeout=100.0,                      # per HTTP request, seconds
+    http_client=my_httpx_client,        # inject your own httpx.Client
+)
+```
+
+`solve()` takes its own `timeout` (seconds, default 180) for the overall wait.
+
+## Typing
+
+The package ships a `py.typed` marker and full inline annotations. Solves come back as frozen dataclasses with the exact field names the API uses (`solve.token`, `solve.credits_charged`, `solve.queue_ms`), so what you read in the [API reference](https://nonecap.com/api-reference) is what you get in code.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

nonecap-0.1.0/README.md

@@ -0,0 +1,159 @@
+<h1 align="center">nonecap</h1>
+
+<p align="center">
+  <a href="https://github.com/nonecap/nonecap-py/actions/workflows/ci.yml"><img src="https://github.com/nonecap/nonecap-py/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/nonecap/"><img src="https://img.shields.io/pypi/v/nonecap.svg" alt="PyPI"></a>
+  <a href="https://pypi.org/project/nonecap/"><img src="https://img.shields.io/pypi/pyversions/nonecap.svg" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">Official Python client for the <a href="https://nonecap.com">NoneCap</a> hCaptcha solving API.</p>
+
+Submit a captcha, get back a token. The client handles the polling, the timeouts, and the error cases so you don't write the request loop yourself. Sync and async, fully typed.
+
+## Install
+
+```sh
+pip install nonecap
+```
+
+Python 3.9+. The only dependency is [httpx](https://www.python-httpx.org/).
+
+## Quick start
+
+Grab an API key from [dashboard.nonecap.com](https://dashboard.nonecap.com), then:
+
+```python
+from nonecap import NoneCap
+
+nc = NoneCap(api_key="nc_live_...")
+
+solve = nc.solve(
+    type="hcaptcha",
+    sitekey="10000000-ffff-ffff-ffff-000000000001",
+    url="https://example.com/login",
+)
+
+print(solve.token)  # the hCaptcha token, ready to submit
+```
+
+`solve()` submits the captcha and waits until it's done, using the API's long-poll so you aren't hammering it with requests. It returns the solved solve, or raises if the solve fails or your timeout runs out.
+
+## Async
+
+Same surface, `await`ed. Use it as an async context manager so the connection pool gets cleaned up:
+
+```python
+import asyncio
+from nonecap import AsyncNoneCap
+
+async def main() -> None:
+    async with AsyncNoneCap(api_key="nc_live_...") as nc:
+        solve = await nc.solve(type="hcaptcha", sitekey="...", url="https://example.com")
+        print(solve.token)
+
+asyncio.run(main())
+```
+
+## Handling failures
+
+Every error this library raises extends `NoneCapError`, so you can catch the whole family or pick out the one you care about.
+
+```python
+from nonecap import (
+    NoneCap,
+    SolveFailedError,
+    InsufficientCreditsError,
+    RateLimitError,
+)
+
+try:
+    solve = nc.solve(type="hcaptcha", sitekey=sitekey, url=url)
+except SolveFailedError as err:
+    print("Could not solve it:", err.solve.error.code if err.solve.error else "?")
+except InsufficientCreditsError:
+    print("Out of credits. Top up at dashboard.nonecap.com")
+except RateLimitError:
+    print("Too many solves in flight, back off and retry")
+```
+
+The subclasses are `AuthenticationError` (401), `PermissionDeniedError` (403), `InsufficientCreditsError` (402), `ValidationError` (422/400, with a `param` naming the bad field), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429), `APIError` (5xx), `APIConnectionError` and `APITimeoutError` (the request never landed), and `SolveTimeoutError` (your `solve()` budget ran out). `SolveFailedError` carries the full `solve` so you can read the underlying error code and the timings.
+
+## Enterprise captchas
+
+For `hcaptcha_enterprise`, `rqdata` is required. The `@overload` signatures enforce that in mypy and pyright, so leaving it out fails your type check, and a runtime check backs it up before any network call:
+
+```python
+solve = nc.solve(
+    type="hcaptcha_enterprise",
+    sitekey=sitekey,
+    url=url,
+    rqdata="...",  # required for enterprise
+)
+```
+
+## Proxies
+
+Pass a proxy as a dict or a URL string. The solve runs through it, and the bytes are metered back on the solve.
+
+```python
+nc.solve(
+    type="hcaptcha",
+    sitekey=sitekey,
+    url=url,
+    proxy={"scheme": "http", "host": "1.2.3.4", "port": 8080, "username": "u", "password": "p"},
+    # or: proxy="http://u:p@1.2.3.4:8080"
+)
+```
+
+## Lower-level API
+
+`solve()` is the convenient path. When you want control over submission and polling, the resource methods map one to one to the REST API:
+
+```python
+# Submit without waiting: returns immediately with a pending solve
+pending = nc.solves.create(type="hcaptcha", sitekey=sitekey, url=url)
+
+# Submit and hold the connection up to 30s for it to finish
+maybe_done = nc.solves.create(type="hcaptcha", sitekey=sitekey, url=url, wait=30)
+
+# Poll one solve, long-polling up to 30s
+solve = nc.solves.retrieve(pending.id, wait=30)
+
+# Cancel a pending or in-flight solve
+nc.solves.cancel(pending.id)
+
+# List a page of solves
+page = nc.solves.list(limit=50, status="solved")
+
+# Or iterate every solve, newest first
+for s in nc.solves.list_all():
+    print(s.id, s.status)
+
+# Your account and credit balance
+me = nc.me()
+print(me.credits_balance)
+```
+
+On `AsyncNoneCap` the same methods are coroutines, and `list_all()` is an async iterator (`async for s in nc.solves.list_all()`).
+
+## Configuration
+
+```python
+NoneCap(
+    api_key="nc_live_...",              # required
+    base_url="https://api.nonecap.com", # override if you need to
+    timeout=100.0,                      # per HTTP request, seconds
+    http_client=my_httpx_client,        # inject your own httpx.Client
+)
+```
+
+`solve()` takes its own `timeout` (seconds, default 180) for the overall wait.
+
+## Typing
+
+The package ships a `py.typed` marker and full inline annotations. Solves come back as frozen dataclasses with the exact field names the API uses (`solve.token`, `solve.credits_charged`, `solve.queue_ms`), so what you read in the [API reference](https://nonecap.com/api-reference) is what you get in code.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

nonecap-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nonecap"
+dynamic = ["version"]
+description = "Official Python client for the NoneCap hCaptcha solving API."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Lunium" }]
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.24"]
+keywords = [
+  "nonecap",
+  "hcaptcha",
+  "captcha",
+  "captcha-solver",
+  "hcaptcha-solver",
+  "api-client",
+  "sdk",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://nonecap.com"
+Documentation = "https://nonecap.com/api-reference"
+Repository = "https://github.com/nonecap/nonecap-py"
+Issues = "https://github.com/nonecap/nonecap-py/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+  "mypy>=1.13",
+  "ruff>=0.8",
+]
+
+[tool.hatch.version]
+path = "src/nonecap/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nonecap"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+warn_unused_ignores = true
+files = ["src/nonecap", "tests/typing_assertions.py"]
+
+[tool.ruff]
+line-length = 96
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+# UP006/UP007/UP045: keep typing.Optional/Union and dict/list generics as written —
+# the floor is 3.9 and `X | None` in runtime positions needs 3.10.
+ignore = ["UP006", "UP007", "UP045"]

nonecap-0.1.0/src/nonecap/__init__.py

@@ -0,0 +1,66 @@
+"""Official Python client for the NoneCap hCaptcha solving API.
+
+>>> from nonecap import NoneCap
+>>> nc = NoneCap(api_key="nc_live_...")
+>>> solve = nc.solve(type="hcaptcha", sitekey="...", url="https://example.com")
+>>> solve.token
+'P1_...'
+"""
+
+from ._client import AsyncNoneCap, NoneCap
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    InsufficientCreditsError,
+    NoneCapError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    SolveFailedError,
+    SolveTimeoutError,
+    ValidationError,
+)
+from ._types import (
+    TERMINAL_STATUSES,
+    Account,
+    Proxy,
+    Solve,
+    SolveError,
+    SolvePage,
+    SolveStatus,
+    SolveType,
+)
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    # clients
+    "NoneCap",
+    "AsyncNoneCap",
+    # types
+    "Solve",
+    "SolveError",
+    "SolvePage",
+    "Account",
+    "Proxy",
+    "SolveType",
+    "SolveStatus",
+    "TERMINAL_STATUSES",
+    # errors
+    "NoneCapError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "InsufficientCreditsError",
+    "ValidationError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "APIError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "SolveFailedError",
+    "SolveTimeoutError",
+]