Metadata-Version: 2.4
Name: datafun-toolkit
Version: 1.0.0
Summary: Privacy-safe diagnostics, paths, and logging helpers for analytics projects.
Author-email: Denise Case <dcase@nwmissouri.edu>
Project-URL: Documentation, https://denisecase.github.io/datafun-toolkit/
Project-URL: Issues, https://github.com/denisecase/datafun-toolkit/issues
Project-URL: Repository, https://github.com/denisecase/datafun-toolkit
Keywords: data,analytics,logging,diagnostics,education,toolkit
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Typing :: Typed
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: bandit>=1.9.4; extra == "dev"
Requires-Dist: deptry>=0.24.0; extra == "dev"
Requires-Dist: packaging>=26.0; extra == "dev"
Requires-Dist: pre-commit>=4.5.1; extra == "dev"
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: pyright>=1.1.408; extra == "dev"
Requires-Dist: ruff>=0.14.13; extra == "dev"
Requires-Dist: validate-pyproject>=0.24.1; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocstrings[python]>=1.0.0; extra == "docs"
Requires-Dist: zensical>=0.0.24; extra == "docs"
Dynamic: license-file

# Data Analytics Fundamentals: Toolkit

[![PyPI version](https://img.shields.io/pypi/v/datafun-toolkit)](https://pypi.org/project/datafun-toolkit/)
[![Latest Release](https://img.shields.io/github/v/release/denisecase/datafun-toolkit)](https://github.com/denisecase/datafun-toolkit/releases)
[![Docs](https://img.shields.io/badge/docs-live-blue)](https://denisecase.github.io/datafun-toolkit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/MIT)
[![CI](https://github.com/denisecase/datafun-toolkit/actions/workflows/ci-python-zensical.yml/badge.svg?branch=main)](https://github.com/denisecase/datafun-toolkit/actions/workflows/ci-python-zensical.yml)
[![Deploy-Docs](https://github.com/denisecase/datafun-toolkit/actions/workflows/deploy-zensical.yml/badge.svg?branch=main)](https://github.com/denisecase/datafun-toolkit/actions/workflows/deploy-zensical.yml)
[![Check Links](https://github.com/denisecase/datafun-toolkit/actions/workflows/links.yml/badge.svg)](https://github.com/denisecase/datafun-toolkit/actions/workflows/links.yml)
[![Dependabot](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg)](https://github.com/denisecase/datafun-toolkit/security)

> Privacy-safe diagnostics, paths, and logging helpers for analytics projects.

## What This Provides

- `get_logger()` for consistent console and file logging
- `log_header()` for a standardized run header
- `log_path()` for privacy-safe path logging
- environment helpers: `detect_shell()`, `detect_os()`, `detect_python()`

This toolkit is designed for reuse.
It works the same locally and in GitHub Actions.

## Install (Choose One)

```shell
uv add datafun-toolkit
```

```shell
pip install datafun-toolkit
```

## Example

```python
import logging
from pathlib import Path
from datafun_toolkit.logger import get_logger, log_header, log_path

LOG: logging.Logger = get_logger("P01", level="DEBUG")

ROOT_PATH: Path = Path.cwd()
DATA_PATH: Path = ROOT_PATH / "data"

def main() -> None:
    """Start the main logic."""
    log_header(LOG, "P01 Pipeline")

    LOG.info("START main()")
    log_path(LOG, "ROOT_PATH", ROOT_PATH)
    log_path(LOG, "DATA_PATH", DATA_PATH)
    LOG.info("Working....")
    LOG.info("END main()")

if __name__ == "__main__":
    main()
```

## Developer Setup

Install tools:

- git
- uv
- VS Code

One-time setup:

```shell
uv self update
uv python pin 3.14
uv sync --extra dev --extra docs --upgrade

uvx pre-commit install
git add -A
uvx pre-commit run --all-files
```

Before starting work:

```shell
git pull
```

After working, run checks:

```shell
uv run ruff format .
uv run ruff check . --fix
uv run pytest --cov=src --cov-report=term-missing

uv run deptry .
uv run bandit -c pyproject.toml -r src
uv run validate-pyproject pyproject.toml
```

Build and serve docs:

```shell
uv run zensical build
uv run zensical serve
```

Hit **CTRL+c** in the VS Code terminal to quit serving.

Save progress frequently (some tools may make changes; you may need to **re-run git `add` and `commit`** to ensure everything gets committed before pushing):

```shell
git add -A
git commit -m "update"
git push -u origin main
```

## Annotations

[ANNOTATIONS.md](./ANNOTATIONS.md)

## Citation

[CITATION.cff](./CITATION.cff)

## License

[MIT](./LICENSE)

## SE Manifest

[SE_MANIFEST.md](./SE_MANIFEST.toml)
