Metadata-Version: 2.4
Name: utilix-sdk
Version: 0.1.0
Summary: 100+ developer utility tools for Python — JSON, encoding, hashing, color, CSS, images, network and more
Project-URL: Homepage, https://utilix.tech
Project-URL: Documentation, https://docs.utilix.tech/sdk/python
Project-URL: Repository, https://github.com/utilix-tech/utilix-sdk-python
Project-URL: Bug Tracker, https://github.com/utilix-tech/utilix-sdk-python/issues
Project-URL: Changelog, https://utilix.tech/changelog
Author-email: Utilix <hello@utilix.tech>
License-Expression: MIT
License-File: LICENSE
Keywords: color,css,developer-tools,devtools,encoding,hashing,image,json,network,sdk,utilities
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: bcrypt>=4.0
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: croniter>=2.0
Requires-Dist: jsonpath-ng>=1.6
Requires-Dist: jsonschema>=4.0
Requires-Dist: lxml>=5.0
Requires-Dist: markdown>=3.5
Requires-Dist: markdownify>=0.11
Requires-Dist: openapi-spec-validator>=0.7
Requires-Dist: pillow>=10.0
Requires-Dist: pyjwt>=2.8
Requires-Dist: python-dateutil>=2.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: qrcode>=7.4
Requires-Dist: requests>=2.31
Requires-Dist: rjsmin>=1.2
Requires-Dist: scour>=0.38
Requires-Dist: semver>=3.0
Requires-Dist: sqlparse>=0.5
Requires-Dist: tinycss2>=1.2
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# utilix-sdk

**100+ developer utility tools for Python — runs entirely locally, no API key required.**

[![PyPI version](https://img.shields.io/pypi/v/utilix-sdk?color=blue)](https://pypi.org/project/utilix-sdk/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Tests](https://img.shields.io/github/actions/workflow/status/utilix-tech/utilix-sdk-python/test.yml?label=tests)](https://github.com/utilix-tech/utilix-sdk-python/actions)

---

## Installation

```bash
pip install utilix-sdk
```

Requires Python 3.11 or later.

---

## Quick Start

### Encoding

```python
from utilix.tools.encoding import encode_base64, decode_base64

result = encode_base64("hello world")
# {"ok": True, "output": "aGVsbG8gd29ybGQ=", "inputBytes": 11, "outputChars": 16}

result = decode_base64("aGVsbG8gd29ybGQ=")
# {"ok": True, "output": "hello world", "outputBytes": 11}
```

### Hashing

```python
from utilix.tools.hashing import hash_all, hash_one

result = hash_all("my-secret")
# Returns MD5, SHA-1, SHA-256, SHA-384, SHA-512 digests in one call

sha256 = hash_one("SHA-256", "my-secret")
# {"ok": True, "algorithm": "SHA-256", "hex": "...", "bits": 256}
```

### JSON Tools

```python
from utilix.tools.json_tools import format_json, minify_json, yaml_to_json

pretty = format_json('{"name":"utilix","version":"0.1.0"}', indent=2)
# {"status": "valid", "output": "{\n  \"name\": \"utilix\", ...", ...}

minified = minify_json('{\n  "a": 1,\n  "b": 2\n}')
# {"ok": True, "output": "{\"a\":1,\"b\":2}", ...}

as_json = yaml_to_json("name: utilix\nversion: 0.1.0")
# {"ok": True, "output": "{\"name\": \"utilix\", \"version\": \"0.1.0\"}"}
```

### Color

```python
from utilix.tools.color import hex_to_rgb, check_contrast, generate_palette

rgb = hex_to_rgb("#3B82F6")
# {"ok": True, "r": 59, "g": 130, "b": 246}

contrast = check_contrast("#FFFFFF", "#3B82F6")
# {"ratio": 3.94, "aa_normal": False, "aa_large": True, "aaa_normal": False, ...}

palette = generate_palette("#3B82F6", scheme="complementary")
# Returns list of hex colors forming a complementary palette
```

### Media

```python
from utilix.tools.media import compress_image, convert_image

with open("photo.jpg", "rb") as f:
    image_bytes = f.read()

result = compress_image(image_bytes, quality=75, format="JPEG")
# {"ok": True, "output": bytes, "original_size": 204800, "compressed_size": 61440, "ratio": 0.3}

converted = convert_image(image_bytes, target_format="WEBP")
# {"ok": True, "output": bytes, "format": "WEBP"}
```

### CSS

```python
from utilix.tools.css import generate_gradient, calc_specificity, minify_css

gradient = generate_gradient({
    "type": "linear",
    "angle": 135,
    "stops": [{"color": "#667eea", "position": 0}, {"color": "#764ba2", "position": 100}]
})
# "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"

specificity = calc_specificity("#nav .item:hover")
# {"score": (0, 1, 1, 1), "display": "0,1,1,1", "explanation": [...]}

minified = minify_css("body {\n  margin: 0;\n  padding: 0;\n}")
# {"ok": True, "output": "body{margin:0;padding:0}", "saved_bytes": 14}
```

### Time Tools

```python
from utilix.tools.time_tools import from_unix, diff_dates, get_next_runs

parsed = from_unix(1735689600)
# {"ok": True, "iso": "2025-01-01T00:00:00+00:00", "relative": "6 months ago", ...}

delta = diff_dates("2024-01-01", "2024-12-31")
# {"ok": True, "days": 365, "months": 12, "human": "12 months"}

schedule = get_next_runs("0 9 * * MON-FRI", count=5)
# Next 5 weekday 9am runs as ISO strings
```

### Network

```python
from utilix.tools.network import ip_to_decimal, cidr_info, is_valid_ipv4

decimal = ip_to_decimal("192.168.1.1")
# {"ok": True, "output": 3232235777}

subnet = cidr_info("10.0.0.0/24")
# {"ok": True, "network": "10.0.0.0", "broadcast": "10.0.0.255",
#  "hosts": 254, "netmask": "255.255.255.0", ...}

print(is_valid_ipv4("256.0.0.1"))  # False
```

---

## Modules

| Module | Description |
|---|---|
| `encoding` | Base64, Base32, URL encoding/decoding, HTML entity encoding |
| `hashing` | MD5, SHA-1/256/384/512 digests, bcrypt password hashing, htpasswd |
| `json_tools` | JSON formatting, minification, diffing, CSV conversion, JSONPath, JSON Schema, YAML-JSON |
| `color` | Color conversion (hex/RGB/HSL/HSV), palettes, contrast ratios, shades/tints, blending |
| `css` | Gradients, box shadows, border radius, animations, cubic bezier, clamp, specificity, minifier |
| `media` | Image compression, format conversion, favicon generation, SVG optimization |
| `time_tools` | Unix timestamp parsing, cron expression parsing, date diffing, timezone conversion |
| `network` | IPv4 conversion, CIDR calculator, DNS lookup (DoH), IP geolocation |
| `api_tools` | cURL builder/parser, cURL-to-code, JWT decode/sign, HTTP status codes, CORS/CSP builders |
| `code` | Regex tester, SQL formatter, HTML formatter/minifier, GraphQL formatter, semver, URL parser, JS minifier |
| `data` | YAML, TOML, XML, CSV, INI, and `.env` file parsing, validation, and conversion |
| `generators` | UUID v4/v7, ULID, password generator, random data, QR code generation |
| `text` | Word counter, case converter, lorem ipsum, slugifier, string escaping, diff viewer, Markdown/HTML |
| `misc` | Unicode analysis, ASCII art, Morse code, JSON-to-TypeScript/Go/Python/Zod schema generation |
| `units` | px/rem/vw conversions, byte formatter, number base conversion, aspect ratio, chmod calculator |

---

## Surface A vs Surface B

### Surface A — this package (`utilix-sdk`)

Everything in this package runs **locally in your Python process**. There are no network calls for the core utilities (DNS lookup and IP geolocation are the only exceptions, and both hit public free APIs). No account, no API key, no rate limits.

```
pip install utilix-sdk
```

Ideal for: scripts, CI pipelines, offline environments, CLIs, and any situation where you want deterministic, zero-cost utility functions.

### Surface B — REST API (`api.utilix.tech/v1`)

The same 100+ tools are also available as a hosted REST API at `https://api.utilix.tech/v1`. This surface requires an API key and is subject to rate limits and pricing tiers.

```bash
curl -X POST https://api.utilix.tech/v1/hashing/sha256 \
  -H "Authorization: Bearer $UTILIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "hello world"}'
```

Ideal for: polyglot teams, environments where installing Python packages is not possible, and browser-based tooling that needs a backend.

---

## Development

```bash
# Clone the repository
git clone https://github.com/utilix-tech/utilix-sdk-python.git
cd utilix-sdk-python

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run the test suite
pytest

# Run with coverage
pytest --cov=utilix --cov-report=term-missing
```

---

## Publishing to PyPI

### Build the distribution

```bash
python -m build
# Produces dist/utilix_sdk-x.y.z.tar.gz and dist/utilix_sdk-x.y.z-py3-none-any.whl
```

### Test on TestPyPI first

```bash
python -m twine upload --repository testpypi dist/*
# Install from TestPyPI to verify
pip install --index-url https://test.pypi.org/simple/ utilix-sdk
```

### Publish to PyPI

```bash
python -m twine upload dist/*
```

### GitHub Actions with OIDC trusted publisher (recommended)

Store no tokens. Configure a trusted publisher on PyPI (Settings > Publishing > Add a new publisher) and use the official PyPA action:

```yaml
# .github/workflows/publish.yml
name: Publish to PyPI

on:
  push:
    tags:
      - "v*"

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # Required for OIDC

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Build
        run: |
          pip install build
          python -m build

      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        # No api-token needed — OIDC trusted publisher handles auth
```

Tag a release (`git tag v0.2.0 && git push --tags`) and the workflow publishes automatically with no stored credentials.

---

## License

MIT. See [LICENSE](LICENSE) for the full text.
