Metadata-Version: 2.1
Name: Crackerjack
Version: 0.8.3
Summary: Crackerjack code style
Keywords: black,ruff,mypy,creosote,refurb
Home-page: https://github.com/lesleslie/crackerjack
Author-Email: lesleslie <les@wedgwoodwebworks.com>
Maintainer-Email: lesleslie <les@wedgwoodwebworks.com>
License: BSD-3-Clause
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.12
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.12
Requires-Dist: click>=8.1.7
Requires-Dist: aioconsole>=0.7.1
Requires-Dist: inflection>=0.5.1
Requires-Dist: autotyping>=24.3.0
Requires-Dist: pre-commit>=3.7.1
Requires-Dist: pytest>=8.2.1
Requires-Dist: pydantic>=2.7.2
Requires-Dist: aiopath>=0.7.7
Requires-Dist: acb>=0.6.2
Requires-Dist: pdm-bump>=0.9.0
Requires-Dist: pdm>=2.15.4
Description-Content-Type: text/markdown

# Crackerjack Python

[![Python: 3.12](https://img.shields.io/badge/python-3.12%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)
[![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.

### **Crackerjack philosophy...**

#### Virtual envs:

Let's face it virtual envs are a mess and a lot of time and resources are
spent maintaining them. [This](https://miro.medium.com/v2/resize:fit:984/format:webp/1*mHrDuetdLskvNHYucD9u3g.png) pretty
much says it all. Enough is enough.

#### Regression testing:

Again, here is what we believe become to be waste of time too. It takes more time to keep codebases compliant
with previous versions of python than it does to just update your code to run the latest versions of python
as they are released (within a liberal-ish timeline of course). Why are you running old versions of python anyway.
There are various easy ways to keep your system python versions up-to-date and
Docker containers for the latest versions are available immediately upon release. Most cloud providers
will support the new versions in their virtual machines and containers shortly after release as well. If your dependencies
break upon upgrade, file a bug report or fix it yourself. Simple enough.

#### ...the Crackerjack solution:

Crackerjack uses PDM with PEP-582 (yes, PEP-582 has been rejected but PDM still supports it and Crackerjack will continue to use it!).
No more virtualenvs. Update your system python versions as they are released and start
migrating your code. Crackerjack, and Crackerjack'd packages, should support the latest
python release's features within 2 month after the release and depend solely on that version. Again, if
something breaks, file a bug report or, even better, fix it yourself (maybe even learn something new things in the process).
Easy-peasy. You just saved yourself a zillion headaches and can sleep
better at night now.

### **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)
  * [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 and PEP-582(proposed) for dependency management and package building/publishing

- use pdoc and mkdocs for producing documentation

- use pytest for testing

- be compliant with 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.

### **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
