Metadata-Version: 2.4
Name: neutronium
Version: 0.2.0
Summary: Framework-agnostic Python utilities: text, time, iterables, structured logging, telemetry primitives, and more.
License-Expression: MIT
Project-URL: Homepage, https://github.com/gaussian/neutronium
Project-URL: Issues, https://github.com/gaussian/neutronium/issues
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: text
Requires-Dist: inflection; extra == "text"
Provides-Extra: time
Requires-Dist: python-dateutil; extra == "time"
Provides-Extra: memory
Requires-Dist: psutil; extra == "memory"
Provides-Extra: memory-extended
Requires-Dist: pympler; extra == "memory-extended"
Requires-Dist: objgraph; extra == "memory-extended"
Provides-Extra: aws
Requires-Dist: boto3>=1.36; extra == "aws"
Requires-Dist: requests>=2.23; extra == "aws"
Requires-Dist: ec2-metadata; extra == "aws"
Provides-Extra: url
Requires-Dist: tldextract; extra == "url"
Provides-Extra: requests
Requires-Dist: requests>=2.23; extra == "requests"
Requires-Dist: idna; extra == "requests"
Provides-Extra: xpath
Requires-Dist: lxml; extra == "xpath"
Provides-Extra: otel
Requires-Dist: opentelemetry-api; extra == "otel"
Provides-Extra: profiling
Requires-Dist: line_profiler; extra == "profiling"
Dynamic: license-file

# neutronium

Framework-agnostic Python utilities, extracted from Gaussian's internal
infrastructure. No Django, no web framework, no cloud SDK in the base install —
everything third-party is an optional extra.

```sh
pip install neutronium              # base: zero dependencies
pip install neutronium[text]        # inflection-backed pluralize/singularize
pip install neutronium[xpath]       # lxml-backed HTML/XPath helpers
```

## What's inside

| Module | What it gives you |
|---|---|
| `neutronium.utils.text` | Text normalization, slugs, tokenization, pluralize/singularize |
| `neutronium.utils.time` | Timezone-aware datetime helpers |
| `neutronium.utils.iterable` | Chunking, grouping, flattening, dict utilities |
| `neutronium.utils.template_context` | Pure template-variable extraction and context building |
| `neutronium.utils.json_patch` | RFC-6901 JSON pointer / merge-patch primitives |
| `neutronium.utils.hash` | `blake2b` content hashing helpers |
| `neutronium.utils.schema` | JSON-schema → default-dict |
| `neutronium.utils.xpath` | lxml HTML parsing + link extraction (`[xpath]`) |
| `neutronium.utils.url` | URL parse / canonicalize / normalize / domain extraction (`[url]`) |
| `neutronium.requester` | Resilient HTTP fetcher with retries/paywall/no-index detection (`[requests]`) |
| `neutronium.utils.file` | Pickle / text / JSONC file helpers |
| `neutronium.utils.performance` | Simple multi-level timer |
| `neutronium.utils.email` | Canonical email normalization |
| `neutronium.utils.{aws,ssm,s3}` | EC2/ECS instance metadata, SSM parameter fetch, S3 upload/download (`[aws]`) |
| `neutronium.utils.{print,params,profiling,memory,url_credentials}` | Assorted small utilities |
| `neutronium.threads.thread_simple` | Minimal threading helpers |
| `neutronium.telemetry` | Request-context vars, `RequestFacts`, pluggable sinks |
| `neutronium.logging` | JSON / dev-console log formatters and context filters |

## Optional extras

`text`, `time`, `aws`, `url`, `requester`, `memory`, `memory-extended`, `xpath`, `otel`, `profiling` — install only what you use.

- `aws` → `boto3`, `requests`, `ec2-metadata` (for `neutronium.utils.aws` / `ssm` / `s3`)
- `url` → `tldextract` (only for `get_url_domain`; the rest of `neutronium.utils.url` is pure stdlib)
- `memory` → `psutil` (for `print_memory_usage`); `memory-extended` → `pympler`, `objgraph` (for the heap/objgraph tools — opt in only if you use them)

## Development

```sh
uv sync --group dev
uv run pytest
```

## License

MIT © Gaussian Holdings, LLC
