rftools-io 0.1.0__tar.gz

rftools_io-0.1.0/LICENSE

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

rftools_io-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: rftools-io
+Version: 0.1.0
+Summary: Python client for rftools.io — 203 RF & electronics calculators
+Author-email: "rftools.io" <hello@rftools.io>
+License-Expression: MIT
+Project-URL: Homepage, https://rftools.io
+Project-URL: Documentation, https://rftools.io/docs/python
+Project-URL: Repository, https://github.com/rftools/rftools-py
+Project-URL: Bug Tracker, https://github.com/rftools/rftools-py/issues
+Keywords: rf,electronics,calculator,antenna,pcb,signal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+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: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: click>=8.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# rftools
+
+[![PyPI](https://img.shields.io/pypi/v/rftools)](https://pypi.org/project/rftools/)
+[![Python](https://img.shields.io/pypi/pyversions/rftools)](https://pypi.org/project/rftools/)
+
+Python client for **rftools.io** — 203 RF & electronics calculators accessible from Python and the command line.
+
+## Installation
+
+```bash
+pip install rftools-io
+```
+
+## Quick Start (free tier)
+
+No API key needed. Free tier: 5 calls/day per IP.
+
+```python
+import rftools
+
+result = rftools.calculate("vswr-return-loss", {"vswr": 2.5})
+print(result["returnLoss"])  # 9.54 dB
+print(result.values)         # {"returnLoss": 9.54, "reflectionCoeff": 0.333, ...}
+```
+
+## Authenticated Usage (API tier)
+
+Get an API key at [rftools.io/pricing](https://rftools.io/pricing) ($19/mo, 10,000 calls/month).
+
+```python
+import rftools
+
+client = rftools.Client(api_key="rfc_live_xxx")
+# or set environment variable: export RFTOOLS_API_KEY=rfc_live_xxx
+
+result = client.calculate("free-space-path-loss", {"frequency": 2400, "distance": 100})
+print(result["pathLoss"])  # dB
+```
+
+## Batch Calculations
+
+Run up to 50 calculations in a single HTTP request (API tier only):
+
+```python
+results = client.batch([
+    ("vswr-return-loss", {"vswr": 1.5}),
+    ("vswr-return-loss", {"vswr": 2.0}),
+    ("free-space-path-loss", {"frequency": 2400, "distance": 50}),
+])
+for r in results:
+    if r.ok:
+        print(r.values)
+    else:
+        print(f"Error: {r.error}")
+```
+
+## Typed Category Stubs
+
+IDE-friendly typed functions with parameter defaults matching the web UI:
+
+```python
+from rftools.calculators import rf, pcb, antenna, power
+
+# RF
+result = rf.vswr_return_loss(vswr=2.5)
+result = rf.free_space_path_loss(frequency=2400.0, distance=100.0)
+
+# Antenna
+result = antenna.dipole_antenna(frequency=433.0)
+result = antenna.parabolic_dish_antenna(frequency=10000.0, diameter=0.6)
+
+# PCB
+result = pcb.trace_width_current(current=2.0, tempRise=10.0, thickness=1.0)
+
+# Power
+result = power.voltage_divider(vin=12.0, r1=10000.0, r2=10000.0)
+```
+
+All 13 categories available: `rf`, `pcb`, `power`, `signal`, `antenna`, `general`, `motor`, `protocol`, `emc`, `thermal`, `sensor`, `unit_conversion`, `audio`.
+
+## CLI
+
+```bash
+# Run a calculation
+rftools calc vswr-return-loss --vswr 2.5
+
+# With API key
+RFTOOLS_API_KEY=rfc_xxx rftools calc free-space-path-loss --frequency 2400 --distance 100
+
+# JSON output (pipe to jq)
+rftools calc vswr-return-loss --vswr 2.5 --json | jq '.values.returnLoss'
+
+# List all calculators
+rftools list
+
+# Filter by category
+rftools list --category rf
+
+# Show calculator inputs/outputs
+rftools info free-space-path-loss
+
+# Library version
+rftools version
+```
+
+## Error Handling
+
+```python
+from rftools.exceptions import AuthError, RateLimitError, ValidationError, NotFoundError, APIError
+
+try:
+    result = client.calculate("vswr-return-loss", {"vswr": 2.5})
+except RateLimitError as e:
+    print(f"Quota exceeded. Retry after: {e.retry_after}s")
+except AuthError:
+    print("Invalid API key")
+except NotFoundError:
+    print("Unknown calculator slug")
+except ValidationError as e:
+    print(f"Bad inputs: {e.detail}")
+```
+
+| Exception | When |
+|---|---|
+| `AuthError` | Invalid or missing API key |
+| `RateLimitError` | Monthly quota exceeded |
+| `ValidationError` | Bad inputs (HTTP 422) |
+| `NotFoundError` | Unknown calculator slug |
+| `APIError` | Unexpected HTTP error |
+
+## Async Support
+
+```python
+import asyncio
+import rftools
+
+async def main():
+    async with rftools.AsyncClient(api_key="rfc_live_xxx") as client:
+        result = await client.calculate("vswr-return-loss", {"vswr": 2.5})
+        print(result["returnLoss"])
+
+asyncio.run(main())
+```
+
+Ideal for running many calculations concurrently in FastAPI or async scripts.
+
+## Browse the Catalog
+
+```python
+# List all calculators
+calcs = rftools.list_calculators()
+print(f"{len(calcs)} calculators available")
+
+# Filter by category
+rf_calcs = rftools.list_calculators(category="rf")
+for c in rf_calcs:
+    print(f"{c.slug}: {c.title}")
+
+# Get a single calculator's metadata
+info = rftools.get_calculator("vswr-return-loss")
+print(info.inputs)   # tuple of InputField
+print(info.outputs)  # tuple of OutputField
+```
+
+## All Calculator Categories
+
+| Category | Count | Example |
+|---|---|---|
+| `rf` | 26 | `vswr-return-loss`, `free-space-path-loss`, `rf-link-budget` |
+| `pcb` | 13 | `trace-width-current`, `via-calculator`, `microstrip-impedance` |
+| `power` | 20 | `voltage-divider`, `led-resistor`, `battery-life` |
+| `signal` | 13 | `filter-designer`, `op-amp-gain`, `pwm-duty-cycle` |
+| `antenna` | 8 | `dipole-antenna`, `eirp-calculator`, `parabolic-dish-antenna` |
+| `general` | 21 | `lc-resonance`, `ohms-law`, `rc-time-constant` |
+| `motor` | 18 | `brushless-dc-motor`, `stepper-motor`, `servo-motor` |
+| `protocol` | 11 | `uart-baud-rate`, `i2c-pullup`, `can-bus-bit-timing` |
+| `emc` | 16 | `emi-filter-lc`, `shielding-effectiveness`, `ground-loop` |
+| `thermal` | 6 | `thermal-resistance`, `heat-sink`, `junction-temperature` |
+| `sensor` | 17 | `thermistor-ntc`, `strain-gauge`, `hall-effect` |
+| `unit-conversion` | 17 | `dbm-watts`, `frequency-wavelength`, `temperature` |
+| `audio` | 17 | `speaker-crossover`, `amplifier-gain`, `room-acoustics` |
+
+## Contributing
+
+Regenerate stubs after calculator changes:
+
+```bash
+python scripts/generate_stubs.py --frontend-dir /path/to/rfhub/frontend
+```
+
+Then bump the version in `pyproject.toml` and publish a new release.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

rftools_io-0.1.0/README.md

@@ -0,0 +1,195 @@
+# rftools
+
+[![PyPI](https://img.shields.io/pypi/v/rftools)](https://pypi.org/project/rftools/)
+[![Python](https://img.shields.io/pypi/pyversions/rftools)](https://pypi.org/project/rftools/)
+
+Python client for **rftools.io** — 203 RF & electronics calculators accessible from Python and the command line.
+
+## Installation
+
+```bash
+pip install rftools-io
+```
+
+## Quick Start (free tier)
+
+No API key needed. Free tier: 5 calls/day per IP.
+
+```python
+import rftools
+
+result = rftools.calculate("vswr-return-loss", {"vswr": 2.5})
+print(result["returnLoss"])  # 9.54 dB
+print(result.values)         # {"returnLoss": 9.54, "reflectionCoeff": 0.333, ...}
+```
+
+## Authenticated Usage (API tier)
+
+Get an API key at [rftools.io/pricing](https://rftools.io/pricing) ($19/mo, 10,000 calls/month).
+
+```python
+import rftools
+
+client = rftools.Client(api_key="rfc_live_xxx")
+# or set environment variable: export RFTOOLS_API_KEY=rfc_live_xxx
+
+result = client.calculate("free-space-path-loss", {"frequency": 2400, "distance": 100})
+print(result["pathLoss"])  # dB
+```
+
+## Batch Calculations
+
+Run up to 50 calculations in a single HTTP request (API tier only):
+
+```python
+results = client.batch([
+    ("vswr-return-loss", {"vswr": 1.5}),
+    ("vswr-return-loss", {"vswr": 2.0}),
+    ("free-space-path-loss", {"frequency": 2400, "distance": 50}),
+])
+for r in results:
+    if r.ok:
+        print(r.values)
+    else:
+        print(f"Error: {r.error}")
+```
+
+## Typed Category Stubs
+
+IDE-friendly typed functions with parameter defaults matching the web UI:
+
+```python
+from rftools.calculators import rf, pcb, antenna, power
+
+# RF
+result = rf.vswr_return_loss(vswr=2.5)
+result = rf.free_space_path_loss(frequency=2400.0, distance=100.0)
+
+# Antenna
+result = antenna.dipole_antenna(frequency=433.0)
+result = antenna.parabolic_dish_antenna(frequency=10000.0, diameter=0.6)
+
+# PCB
+result = pcb.trace_width_current(current=2.0, tempRise=10.0, thickness=1.0)
+
+# Power
+result = power.voltage_divider(vin=12.0, r1=10000.0, r2=10000.0)
+```
+
+All 13 categories available: `rf`, `pcb`, `power`, `signal`, `antenna`, `general`, `motor`, `protocol`, `emc`, `thermal`, `sensor`, `unit_conversion`, `audio`.
+
+## CLI
+
+```bash
+# Run a calculation
+rftools calc vswr-return-loss --vswr 2.5
+
+# With API key
+RFTOOLS_API_KEY=rfc_xxx rftools calc free-space-path-loss --frequency 2400 --distance 100
+
+# JSON output (pipe to jq)
+rftools calc vswr-return-loss --vswr 2.5 --json | jq '.values.returnLoss'
+
+# List all calculators
+rftools list
+
+# Filter by category
+rftools list --category rf
+
+# Show calculator inputs/outputs
+rftools info free-space-path-loss
+
+# Library version
+rftools version
+```
+
+## Error Handling
+
+```python
+from rftools.exceptions import AuthError, RateLimitError, ValidationError, NotFoundError, APIError
+
+try:
+    result = client.calculate("vswr-return-loss", {"vswr": 2.5})
+except RateLimitError as e:
+    print(f"Quota exceeded. Retry after: {e.retry_after}s")
+except AuthError:
+    print("Invalid API key")
+except NotFoundError:
+    print("Unknown calculator slug")
+except ValidationError as e:
+    print(f"Bad inputs: {e.detail}")
+```
+
+| Exception | When |
+|---|---|
+| `AuthError` | Invalid or missing API key |
+| `RateLimitError` | Monthly quota exceeded |
+| `ValidationError` | Bad inputs (HTTP 422) |
+| `NotFoundError` | Unknown calculator slug |
+| `APIError` | Unexpected HTTP error |
+
+## Async Support
+
+```python
+import asyncio
+import rftools
+
+async def main():
+    async with rftools.AsyncClient(api_key="rfc_live_xxx") as client:
+        result = await client.calculate("vswr-return-loss", {"vswr": 2.5})
+        print(result["returnLoss"])
+
+asyncio.run(main())
+```
+
+Ideal for running many calculations concurrently in FastAPI or async scripts.
+
+## Browse the Catalog
+
+```python
+# List all calculators
+calcs = rftools.list_calculators()
+print(f"{len(calcs)} calculators available")
+
+# Filter by category
+rf_calcs = rftools.list_calculators(category="rf")
+for c in rf_calcs:
+    print(f"{c.slug}: {c.title}")
+
+# Get a single calculator's metadata
+info = rftools.get_calculator("vswr-return-loss")
+print(info.inputs)   # tuple of InputField
+print(info.outputs)  # tuple of OutputField
+```
+
+## All Calculator Categories
+
+| Category | Count | Example |
+|---|---|---|
+| `rf` | 26 | `vswr-return-loss`, `free-space-path-loss`, `rf-link-budget` |
+| `pcb` | 13 | `trace-width-current`, `via-calculator`, `microstrip-impedance` |
+| `power` | 20 | `voltage-divider`, `led-resistor`, `battery-life` |
+| `signal` | 13 | `filter-designer`, `op-amp-gain`, `pwm-duty-cycle` |
+| `antenna` | 8 | `dipole-antenna`, `eirp-calculator`, `parabolic-dish-antenna` |
+| `general` | 21 | `lc-resonance`, `ohms-law`, `rc-time-constant` |
+| `motor` | 18 | `brushless-dc-motor`, `stepper-motor`, `servo-motor` |
+| `protocol` | 11 | `uart-baud-rate`, `i2c-pullup`, `can-bus-bit-timing` |
+| `emc` | 16 | `emi-filter-lc`, `shielding-effectiveness`, `ground-loop` |
+| `thermal` | 6 | `thermal-resistance`, `heat-sink`, `junction-temperature` |
+| `sensor` | 17 | `thermistor-ntc`, `strain-gauge`, `hall-effect` |
+| `unit-conversion` | 17 | `dbm-watts`, `frequency-wavelength`, `temperature` |
+| `audio` | 17 | `speaker-crossover`, `amplifier-gain`, `room-acoustics` |
+
+## Contributing
+
+Regenerate stubs after calculator changes:
+
+```bash
+python scripts/generate_stubs.py --frontend-dir /path/to/rfhub/frontend
+```
+
+Then bump the version in `pyproject.toml` and publish a new release.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

rftools_io-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rftools-io"
+version = "0.1.0"
+description = "Python client for rftools.io — 203 RF & electronics calculators"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "rftools.io", email = "hello@rftools.io" }]
+keywords = ["rf", "electronics", "calculator", "antenna", "pcb", "signal"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+    "click>=8.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.4",
+    "build",
+    "twine",
+    "pytest-cov>=4.0",
+]
+
+[project.scripts]
+rftools = "rftools._cli:cli"
+
+[project.urls]
+Homepage = "https://rftools.io"
+Documentation = "https://rftools.io/docs/python"
+Repository = "https://github.com/rftools/rftools-py"
+"Bug Tracker" = "https://github.com/rftools/rftools-py/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["rftools*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

rftools_io-0.1.0/rftools/__init__.py

@@ -0,0 +1,68 @@
+# rftools/__init__.py
+"""
+rftools — Python client for rftools.io (203 RF & electronics calculators).
+
+Quick start (free tier, 5 calls/day):
+    import rftools
+    result = rftools.calculate("vswr-return-loss", {"vswr": 2.5})
+    print(result["returnLoss"])  # 9.54
+
+Authenticated (API tier, 10,000 calls/month):
+    client = rftools.Client(api_key="rfc_live_xxx")
+    result = client.calculate("free-space-path-loss", {"frequency": 2400, "distance": 100})
+"""
+import os
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "calculate",
+    "list_calculators",
+    "get_calculator",
+    "CalculatorResult",
+    "CalculatorInfo",
+    "InputField",
+    "OutputField",
+    "RFToolsError",
+    "AuthError",
+    "RateLimitError",
+    "ValidationError",
+    "NotFoundError",
+    "APIError",
+]
+
+from rftools.client import Client, AsyncClient
+from rftools.types import CalculatorResult, CalculatorInfo, InputField, OutputField
+from rftools.exceptions import (
+    RFToolsError, AuthError, RateLimitError, ValidationError, NotFoundError, APIError,
+)
+
+_default_client: Client | None = None
+
+
+def _get_default_client() -> Client:
+    global _default_client
+    env_key = os.environ.get("RFTOOLS_API_KEY")
+    if _default_client is None or (env_key and _default_client._api_key != env_key):
+        _default_client = Client(api_key=env_key)
+    return _default_client
+
+
+def calculate(slug: str, inputs: dict) -> CalculatorResult:
+    """
+    Run a calculator using the free tier (no API key required).
+
+    5 calls/day per IP. For higher limits, use ``rftools.Client(api_key=...)``.
+    """
+    return _get_default_client().calculate(slug, inputs)
+
+
+def list_calculators(category: str | None = None) -> list[CalculatorInfo]:
+    """Return metadata for all 203 calculators, optionally filtered by category."""
+    return _get_default_client().list_calculators(category=category)
+
+
+def get_calculator(slug: str) -> CalculatorInfo:
+    """Return metadata for a single calculator by slug."""
+    return _get_default_client().get_calculator(slug)