Metadata-Version: 2.1
Name: crackerjack
Version: 0.11.4
Summary: Default template for PDM package
Keywords: black,ruff,mypy,creosote,refurb
Author-Email: lesleslie <les@wedgwoodwebworks.com>
Maintainer-Email: lesleslie <les@wedgwoodwebworks.com>
License: BSD-3-CLAUSE
Classifier: Environment :: Console
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.13
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: BSD License
Classifier: Typing :: Typed
Project-URL: homepage, https://github.com/lesleslie/crackerjack
Project-URL: documentation, https://github.com/lesleslie/crackerjack
Project-URL: repository, https://github.com/lesleslie/crackerjack
Requires-Python: >=3.13
Requires-Dist: click>=8.1.8
Requires-Dist: autotyping>=24.9.0
Requires-Dist: pre-commit>=4.1.0
Requires-Dist: pytest>=8.3.5
Requires-Dist: pydantic>=2.10.6
Requires-Dist: pdm-bump>=0.9.10
Requires-Dist: pdm>=2.22.3
Requires-Dist: uv>=0.6.4
Requires-Dist: pytest-cov>=6.0.0
Requires-Dist: pytest-mock>=3.14.0
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: pytest-asyncio>=0.25.3
Description-Content-Type: text/markdown

# Crackerjack Python

[![Python: 3.13](https://img.shields.io/badge/python-3.13%2B-blue)](https://docs.python.org/3/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
[![pdm-managed](https://img.shields.io/badge/pdm-managed-blueviolet)](https://pdm.fming.dev)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
[![Code style: crackerjack](https://img.shields.io/badge/code%20style-crackerjack-000042)](https://github.com/lesleslie/crackerjack)

Crackerjack is a python coding style which uses a minimalist approach to produce elegant, easy to read, code.

crack·​er·​jack ˈkra-kər-ˌjak
: a person or thing of marked excellence

### **Why Crackerjack?**

Crackerjack works on the theory that with static typing and explicit class,
function, variable, and other object names - the code should be
straight forward to read. Documentation and tests should be able to write themselves using a generative ai.
Crackerjack provides a set of guidelines and utilities to keep the codebase clean, elegant, standardized, and
easily readable.

### **What does this package do?**

This package:

- streamlines and standardizes code style across numerous packages

- installs, or updates, a project's pre-commit tools as well as .gitignore & other config files
  to comply with evolving crackerjack standards

- runs the following pre-commit hooks (in order):
  * [pdm-lock-check](https://github.com/pdm-project/pdm)
  * various core [pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks)
  * [ruff](https://github.com/charliermarsh/ruff-pre-commit)
  * [vulture](https://github.com/jendrikseipp/vulture)
  * [creosote](https://github.com/fredrikaverpil/creosote)
  * [flynt](https://github.com/ikamensh/flynt/)
  * [codespell](https://github.com/codespell-project/codespell)
  * [autotyping](https://github.com/JelleZijlstra/autotyping)
  * [refurb](https://github.com/dosisod/refurb)
  * [bandit](https://github.com/PyCQA/bandit)
  * [pyright](https://github.com/RobertCraigie/pyright-python)
  * [ruff](https://github.com/charliermarsh/ruff-pre-commit) (again for sanity checking)

- converts/creates documentation in Markdown (md) (work in progress)

- runs tests and generates pytest mock stubs if needed (work in progress)

- bumps the project version and publishes it to PyPI

- commits changes to git repositories

### **What are the rules?**

(...more what you'd call "guidelines" than actual rules. -Captain Barbossa )

- code is statically typed

- all docstrings, README's, and other documentation is to be done in Markdown (md)

- use aiopath.AsyncPath or pathlib.Path not os.path

- import typing as t

- do not capitalize all letters in configuration settings or constants (we diverge from PEP-8 here
 for not other reason than it looks ugly)

- functions that deal with path operations should get passed AsyncPaths or Paths - not strings

- use PDM (uv support enabled) for dependency management and package building/publishing

- use pdoc and mkdocs for producing documentation

- use pytest for testing

- be compliant with, and only support, the latest python version within 2 months after release



[//]: # (- variable docstrings are supported as outlined in)

[//]: # (  [PEP-224]&#40;https://www.python.org/dev/peps/pep-0224/&#41; as well as the module-level)

[//]: # (  __pdoc__ dictionary &#40;see [pdoc docs]&#40;)

[//]: # (  https://pdoc3.github.io/pdoc/doc/pdoc/#overriding-docstrings-with-__pdoc__&#41;&#41;)


### **Installation**

From your projects root directory:

```pdm add -d crackerjack```

### **Usage**

From your projects root directory:

```python -m crackerjack```

For a full list of options:

```python -m crackerjack -h```

When you ready to publish your project:

``python -m crackerjack -p micro``

The -p option not only publishes your project but will bump your
project version for you. The options are 'micro', 'minor', and 'major'.
Put the -c option at the end and commit the bumped version to your git
repository at the same time:

``python -m crackerjack -p micro -c``

### **Contributing**

Crackerjack is currently an evolving standard. If you like the idea, but don't like certain things about it, or
would like new features added, let me know in Discussions, Issues, or email me.

### **License**

BSD-3-Clause
