Metadata-Version: 2.3
Name: almanack
Version: 0.0.5
Summary: An open-source handbook of applied guidance and tools for sustainable software development and maintenance.
License: BSD-3-Clause
Author: Software Gardening Community
Requires-Python: >=3.9,<=3.12
Classifier: License :: OSI Approved :: BSD License
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
Requires-Dist: charset-normalizer (>=3.4.0,<4.0.0)
Requires-Dist: defusedxml (>=0.7.1,<0.8.0)
Requires-Dist: fire (>=0.6,<0.8)
Requires-Dist: pygit2 (>=1.15.1,<2.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Requires-Dist: tabulate (>=0.9.0,<0.10.0)
Description-Content-Type: text/markdown

# The Software Gardening Almanack

![PyPI - Version](https://img.shields.io/pypi/v/almanack)
[![Build Status](https://github.com/software-gardening/almanack/actions/workflows/pytest-tests.yml/badge.svg?branch=main)](https://github.com/software-gardening/almanack/actions/workflows/pytest-tests.yml?query=branch%3Amain)
![Coverage Status](https://raw.githubusercontent.com/software-gardening/almanack/main/media/coverage-badge.svg)

The Software Gardening Almanack is an open-source handbook of applied guidance and tools for sustainable software development and maintenance.
The Almanack is available both as a handbook and a Python package.

## Handbook

- __Online (HTML)__: https://software-gardening.github.io/almanack/
- __Offline (PDF)__: [software-gardening-almanack.pdf](https://software-gardening.github.io/almanack/software-gardening-almanack.pdf)

## Package

You can install the Almanack with the following:

```bash
# install from pypi
pip install almanack

# install directly from source
pip install git+https://github.com/software-gardening/almanack.git
```

Once installed, the Almanack can be used to analyze repositories for sustainable development practices.
Output from the Almanack includes metrics which are defined through `metrics.yml` as a Python dictionary (JSON-compatible) record structure.

For example:

```python
import almanack
import pandas as pd

# gather the almanack table using the almanack repo as a reference
almanack_table = almanack.metrics.data.get_table("path/to/repository")

# show the almanack table as a Pandas DataFrame
pd.DataFrame(almanack_table)
```

Alternatively, you can use the Almanack package as a command-line interface (CLI):

```bash
# generate a table of metrics based on a repository
almanack table path/to/repository

# perform linting-style checks on a repository
almanack check path/to/repository
```

## Contributing

Please see our [`CONTRIBUTING.md`](CONTRIBUTING.md) document for more information on how to contribute to this project.

## Acknowledgements

This work was supported by the Better Scientific Software Fellowship Program, a collaborative effort of the U.S. Department of Energy (DOE), Office of Advanced Scientific Research via ANL under Contract DE-AC02-06CH11357 and the National Nuclear Security Administration Advanced Simulation and Computing Program via LLNL under Contract DE-AC52-07NA27344; and by the National Science Foundation (NSF) via SHI under Grant No. 2327079.

