Metadata-Version: 2.4
Name: datafun-toolkit
Version: 0.9.5
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 :: 4 - Beta
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: bandit>=1.9.2; extra == "dev"
Requires-Dist: deptry>=0.24.0; extra == "dev"
Requires-Dist: packaging>=25.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.11; extra == "dev"
Requires-Dist: twine>=6.2.0; extra == "dev"
Requires-Dist: validate-pyproject>=0.24.1; extra == "dev"
Provides-Extra: docs
Requires-Dist: mike>=2.1.3; extra == "docs"
Requires-Dist: mkdocs>=1.6.1; extra == "docs"
Requires-Dist: mkdocs-material>=9.7.1; extra == "docs"
Requires-Dist: mkdocs-static-i18n>=1.3.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=1.0.0; 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-mkdocs.yml/badge.svg?branch=main)](https://github.com/denisecase/datafun-toolkit/actions/workflows/ci-python-mkdocs.yml)
[![Deploy-Docs](https://github.com/denisecase/datafun-toolkit/actions/workflows/deploy-mkdocs.yml/badge.svg?branch=main)](https://github.com/denisecase/datafun-toolkit/actions/workflows/deploy-mkdocs.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/dependabot)

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

## What This Provides

- `find_project_root()` and `safe_relpath_str()` for robust, repo-relative paths
- `get_logger()` for consistent console and file logging (using a standard logging API)
- `log_header()` for a privacy-safe logging header (shows OS, shell, Python version, repo-relative cwd)

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
from datafun_toolkit import find_project_root, get_logger, log_header, safe_relpath_str
from pathlib import Path

def main() -> None:
    logger = get_logger("example")
    log_header(logger, "example")

    root = find_project_root()
    logger.info(f"project_root={root.name}")
    logger.info(f"cwd={safe_relpath_str(Path.cwd(), root)}")

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 (hit **CTRL+c** in the VS Code terminal to quit serving):

```shell
uv run mkdocs build --strict
uv run mkdocs serve
```

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)
