humanlog 0.1.0__tar.gz

humanlog-0.1.0/LICENSE

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

humanlog-0.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: humanlog
+Version: 0.1.0
+Summary: One-line progress + logging for humans.
+Author-email: srichs <srichs@pm.me>
+License: MIT
+Project-URL: Homepage, https://github.com/srichs/humanlog
+Project-URL: Repository, https://github.com/srichs/humanlog
+Project-URL: Issues, https://github.com/srichs/humanlog/issues
+Project-URL: Changelog, https://github.com/srichs/humanlog/blob/main/CHANGELOG.md
+Keywords: logging,cli,progress,terminal,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: sphinx>=7.0; extra == "dev"
+Dynamic: license-file
+
+# humanlog
+
+[![CI](https://github.com/srichs/humanlog/actions/workflows/ci.yml/badge.svg)](https://github.com/srichs/humanlog/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/humanlog.svg)](https://pypi.org/project/humanlog/)
+
+One-line logging + progress for humans.  
+Works in terminals, CI, and Jupyter — no setup, no configuration.
+
+```python
+from humanlog import log
+
+log.step("Downloading data")
+...
+log.done(rows=120_000)
+
+log.info("Cleaning finished")
+log.warn("Missing values detected", cols=3)
+```
+
+## Why humanlog?
+
+Most logging tools are either:
+
+- too low-level (stdlib logging),
+- too heavy (structured logging frameworks),
+- or great at one thing (progress bars) but awkward for everything else.
+
+`humanlog` is opinionated and small:
+
+- readable output
+- automatic timing
+- graceful behavior everywhere
+- zero configuration
+
+It’s for applications, scripts, CLIs, and data workflows.
+
+## Install
+
+```bash
+pip install humanlog
+```
+
+Python 3.9+ (no dependencies).
+
+## The core idea
+
+### Steps feel like steps
+
+```python
+log.step("Training model")
+train()
+log.done(loss=0.031)
+```
+
+Output (terminal):
+
+```text
+→ Training model …
+✓ Training model (loss=0.031, time=2.41s)
+```
+
+No manual timers. No formatting. No state.
+
+### Informational messages
+
+```python
+log.info("Loading dataset", rows=120_000)
+log.warn("Missing values detected", cols=3)
+log.error("Failed to connect to database")
+```
+
+Output:
+
+```text
+[12:40:03] ℹ Loading dataset (rows=120000)
+[12:40:04] ⚠ Missing values detected (cols=3)
+[12:40:05] ✖ Failed to connect to database
+```
+
+## Works everywhere
+
+### Terminal (TTY)
+
+- Animated steps
+- Clean overwrite
+- Human-friendly symbols
+
+### CI (GitHub Actions, GitLab, etc.)
+
+- No carriage-return garbage
+- Timestamped, line-by-line logs
+
+### Jupyter notebooks
+
+- No broken progress bars
+- Clean output cells
+
+`humanlog` automatically detects where it’s running and adapts.
+
+Set `HUMANLOG_NO_ANIMATE=1` (or `NO_COLOR=1`) to force non-animated output.
+
+## Zero configuration
+
+No handlers.  
+No log levels to wire up.  
+No global logging side effects.
+
+Just import and go.
+
+## API
+
+### `log.step(message: str)`
+
+Start a timed step.
+
+If another step is already active, `humanlog` automatically finishes it first so
+you never end up with overlapping step state.
+
+You can also use it as a context manager to auto-complete the step:
+
+```python
+with log.step("Training model"):
+    train()
+```
+
+If an exception escapes the block, the step is automatically closed as failed:
+
+```text
+[12:40:05] ✖ Training model (error=RuntimeError, time=0.73s)
+```
+
+### `log.done(**info)`
+
+Finish the current step and print timing + optional key/value info.
+
+### `log.info(message: str, **info)`
+
+Print an informational message.
+
+If a step is active, it is automatically completed before the info line is
+printed.
+
+### `log.warn(message: str, **info)`
+
+Print a warning (to stderr).
+
+If a step is active, it is automatically completed before the warning is
+printed.
+
+### `log.error(message: str, **info)`
+
+Print an error (to stderr).
+
+If a step is active, it is automatically completed before the error is printed.
+
+Key/value info is always optional and rendered inline:
+
+```python
+log.info("Loaded batch", batch=3, rows=1024)
+```
+
+## Example: a real script
+
+```python
+from humanlog import log
+
+log.step("Downloading data")
+download()
+log.done(rows=120_000)
+
+log.step("Cleaning data")
+clean()
+log.done(dropped=341)
+
+log.step("Training model")
+train()
+log.done(epochs=10, loss=0.031)
+
+log.info("All done")
+```
+
+Readable. Intentional. Calm.
+
+## Non-goals (by design)
+
+`humanlog` is not:
+
+- a replacement for structured logging
+- a metrics system
+- a tracing framework
+- a progress-bar DSL
+
+If you need JSON logs or OpenTelemetry, use those tools.
+
+If you want pleasant, readable output, use `humanlog`.
+
+## Roadmap (likely, but optional)
+
+- `log.track(iterable, label="Processing")`
+- optional Rich-powered rendering
+- stdlib logging bridge (opt-in)
+
+The core will stay small.
+
+## Philosophy
+
+`humanlog` optimizes for:
+
+- clarity over flexibility
+- defaults over configuration
+- humans over machines
+
+Logs are for people first.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup and quality checks.
+
+## Changelog
+
+Release history is tracked in [CHANGELOG.md](CHANGELOG.md).
+
+## Releasing
+
+Maintainers can follow [RELEASE.md](RELEASE.md) for packaging, verification, and publish steps.
+
+## License
+
+MIT

humanlog-0.1.0/README.md

@@ -0,0 +1,229 @@
+# humanlog
+
+[![CI](https://github.com/srichs/humanlog/actions/workflows/ci.yml/badge.svg)](https://github.com/srichs/humanlog/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/humanlog.svg)](https://pypi.org/project/humanlog/)
+
+One-line logging + progress for humans.  
+Works in terminals, CI, and Jupyter — no setup, no configuration.
+
+```python
+from humanlog import log
+
+log.step("Downloading data")
+...
+log.done(rows=120_000)
+
+log.info("Cleaning finished")
+log.warn("Missing values detected", cols=3)
+```
+
+## Why humanlog?
+
+Most logging tools are either:
+
+- too low-level (stdlib logging),
+- too heavy (structured logging frameworks),
+- or great at one thing (progress bars) but awkward for everything else.
+
+`humanlog` is opinionated and small:
+
+- readable output
+- automatic timing
+- graceful behavior everywhere
+- zero configuration
+
+It’s for applications, scripts, CLIs, and data workflows.
+
+## Install
+
+```bash
+pip install humanlog
+```
+
+Python 3.9+ (no dependencies).
+
+## The core idea
+
+### Steps feel like steps
+
+```python
+log.step("Training model")
+train()
+log.done(loss=0.031)
+```
+
+Output (terminal):
+
+```text
+→ Training model …
+✓ Training model (loss=0.031, time=2.41s)
+```
+
+No manual timers. No formatting. No state.
+
+### Informational messages
+
+```python
+log.info("Loading dataset", rows=120_000)
+log.warn("Missing values detected", cols=3)
+log.error("Failed to connect to database")
+```
+
+Output:
+
+```text
+[12:40:03] ℹ Loading dataset (rows=120000)
+[12:40:04] ⚠ Missing values detected (cols=3)
+[12:40:05] ✖ Failed to connect to database
+```
+
+## Works everywhere
+
+### Terminal (TTY)
+
+- Animated steps
+- Clean overwrite
+- Human-friendly symbols
+
+### CI (GitHub Actions, GitLab, etc.)
+
+- No carriage-return garbage
+- Timestamped, line-by-line logs
+
+### Jupyter notebooks
+
+- No broken progress bars
+- Clean output cells
+
+`humanlog` automatically detects where it’s running and adapts.
+
+Set `HUMANLOG_NO_ANIMATE=1` (or `NO_COLOR=1`) to force non-animated output.
+
+## Zero configuration
+
+No handlers.  
+No log levels to wire up.  
+No global logging side effects.
+
+Just import and go.
+
+## API
+
+### `log.step(message: str)`
+
+Start a timed step.
+
+If another step is already active, `humanlog` automatically finishes it first so
+you never end up with overlapping step state.
+
+You can also use it as a context manager to auto-complete the step:
+
+```python
+with log.step("Training model"):
+    train()
+```
+
+If an exception escapes the block, the step is automatically closed as failed:
+
+```text
+[12:40:05] ✖ Training model (error=RuntimeError, time=0.73s)
+```
+
+### `log.done(**info)`
+
+Finish the current step and print timing + optional key/value info.
+
+### `log.info(message: str, **info)`
+
+Print an informational message.
+
+If a step is active, it is automatically completed before the info line is
+printed.
+
+### `log.warn(message: str, **info)`
+
+Print a warning (to stderr).
+
+If a step is active, it is automatically completed before the warning is
+printed.
+
+### `log.error(message: str, **info)`
+
+Print an error (to stderr).
+
+If a step is active, it is automatically completed before the error is printed.
+
+Key/value info is always optional and rendered inline:
+
+```python
+log.info("Loaded batch", batch=3, rows=1024)
+```
+
+## Example: a real script
+
+```python
+from humanlog import log
+
+log.step("Downloading data")
+download()
+log.done(rows=120_000)
+
+log.step("Cleaning data")
+clean()
+log.done(dropped=341)
+
+log.step("Training model")
+train()
+log.done(epochs=10, loss=0.031)
+
+log.info("All done")
+```
+
+Readable. Intentional. Calm.
+
+## Non-goals (by design)
+
+`humanlog` is not:
+
+- a replacement for structured logging
+- a metrics system
+- a tracing framework
+- a progress-bar DSL
+
+If you need JSON logs or OpenTelemetry, use those tools.
+
+If you want pleasant, readable output, use `humanlog`.
+
+## Roadmap (likely, but optional)
+
+- `log.track(iterable, label="Processing")`
+- optional Rich-powered rendering
+- stdlib logging bridge (opt-in)
+
+The core will stay small.
+
+## Philosophy
+
+`humanlog` optimizes for:
+
+- clarity over flexibility
+- defaults over configuration
+- humans over machines
+
+Logs are for people first.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup and quality checks.
+
+## Changelog
+
+Release history is tracked in [CHANGELOG.md](CHANGELOG.md).
+
+## Releasing
+
+Maintainers can follow [RELEASE.md](RELEASE.md) for packaging, verification, and publish steps.
+
+## License
+
+MIT

humanlog-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "humanlog"
+version = "0.1.0"
+description = "One-line progress + logging for humans."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    {name = "srichs", email = "srichs@pm.me"},
+]
+license = {text = "MIT"}
+keywords = ["logging", "cli", "progress", "terminal", "developer-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Logging",
+]
+
+[project.urls]
+Homepage = "https://github.com/srichs/humanlog"
+Repository = "https://github.com/srichs/humanlog"
+Issues = "https://github.com/srichs/humanlog/issues"
+Changelog = "https://github.com/srichs/humanlog/blob/main/CHANGELOG.md"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+packages = ["humanlog"]
+
+
+[project.optional-dependencies]
+dev = [
+    "black>=24.0",
+    "mypy>=1.0",
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.5",
+    "sphinx>=7.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

humanlog-0.1.0/setup.cfg

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

humanlog-0.1.0/src/humanlog/__init__.py

@@ -0,0 +1,7 @@
+"""humanlog: one-line progress + logging for humans."""
+
+from .core import HumanLog
+
+__all__ = ["HumanLog", "log"]
+
+log = HumanLog()