diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..5cadf7a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,15 @@ +# changelog + +See also: [Github Release Page](https://github.com/enpaul/peewee-plus/releases). + +## Version 1.0.0 + +View this release on: [Github](https://github.com/enpaul/peewee-plus/releases/tag/1.0.0), +[PyPI](https://pypi.org/project/peewee-plus/1.0.0/) + +- Add function for calculating SQLite batch size +- Add constants for SQLite default parameters +- Add field for storing JSON-serializable data +- Add field for storing Enums +- Add field for storing paths +- Add field for storing floats with custom precision parameters diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..2382d9d --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,115 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a +harassment-free experience for everyone, regardless of age, body size, visible or +invisible disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal appearance, +race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, +inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning + from the experience +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their + explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable +behavior and will take appropriate and fair corrective action in response to any behavior +that they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, +commits, code, wiki edits, issues, and other contributions that are not aligned to this +Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an +individual is officially representing the community in public spaces. Examples of +representing our community include using an official e-mail address, posting via an +official social media account, or acting as an appointed representative at an online or +offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the +community leaders responsible for enforcement at \[INSERT CONTACT METHOD\]. All +complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of +any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the +consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing clarity +around the nature of the violation and an explanation of why the behavior was +inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behavior. No interaction with +the people involved, including unsolicited interaction with those enforcing the Code of +Conduct, for a specified period of time. This includes avoiding interactions in community +spaces as well as external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained +inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public communication with +the community for a specified period of time. No public or private interaction with the +people involved, including unsolicited interaction with those enforcing the Code of +Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, +including sustained inappropriate behavior, harassment of an individual, or aggression +toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, +available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. + +[homepage]: https://www.contributor-covenant.org diff --git a/README.md b/README.md index f8bd476..2157d63 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,118 @@ # peewee+ Various extensions, helpers, and utilities for [Peewee](http://peewee-orm.com) + +[![PyPI Version](https://img.shields.io/pypi/v/peewee-plus)](https://pypi.org/project/peewee-plus/) +[![License](https://img.shields.io/pypi/l/peewee-plus)](https://opensource.org/licenses/MIT) +[![Python Supported Versions](https://img.shields.io/pypi/pyversions/peewee-plus)](https://www.python.org) +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) + +See the [Changelog](https://github.com/enpaul/peewee-plus/blob/devel/CHANGELOG.md) for +release history. + +## Documentation + +*The documentation for this project is currently a work in progress. Please see the source code for complete docs* + +- [Installing](#installing) +- [Features](#features) +- [For Developers](#for-developers) + +## Installing + +Peewee+ is [available on PyPI](https://pypi.org/project/peewee-plus/) and can be installed +using Poetry, Pipenv, or Pip: + +```bash +# Using poetry +poetry add peewee-plus + +# Using pipenv +pipenv install peewee-plus + +# Using pip +python -m venv peewee +source peewee/bin/activate +python -m pip install peewee-plus +``` + +Once installed, Peewee+ can be imported like below: + +```python +import peewee_plus +``` + +## Features + +### Constants + +`SQLITE_DEFAULT_PRAGMAS` - The default pragmas to use with an SQLite database connection, +taken directly from the +[Peewee docs](http://docs.peewee-orm.com/en/latest/peewee/database.html#recommended-settings). + +`SQLITE_DEFAULT_VARIABLE_LIMIT` - The maximum number of variables an SQL query can use +when using SQLite + +### Functions + +[`calc_batch_size`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L68) - +Helper function for determining how to batch a create/update query with SQLite + +### Classes + +[`PathField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#134) - A +Peewee database field for storing +[Pathlib](https://docs.python.org/3/library/pathlib.html) objects, optionally relative to +a runtime value. + +[`PrecisionFloatField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L192) +\- A Peewee database field for storing floats while specifying the +[MySQL precision parameters](https://dev.mysql.com/doc/refman/8.0/en/floating-point-types.html) +`M` and `D` + +[`JSONField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L222) - A +Peewee database field for storing arbitrary JSON-serializable data + +[`EnumField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L277) - A +Peewee database field for storing Enums by name + +## For Developers + +All project contributors and participants are expected to adhere to the +[Contributor Covenant Code of Conduct, v2](CODE_OF_CONDUCT.md) ([external link](https://www.contributor-covenant.org/version/2/0/code_of_conduct/)). + +The `devel` branch has the latest (and potentially unstable) changes. The stable releases +are tracked on [Github](https://github.com/enpaul/peewee-plus/releases), +[PyPi](https://pypi.org/project/peewee-plus/#history), and in the +[Changelog](CHANGELOG.md). + +- To report a bug, request a feature, or ask for assistance, please + [open an issue on the Github repository](https://github.com/enpaul/peewee-plus/issues/new). +- To report a security concern or code of conduct violation, please contact the project + author directly at **‌me \[at‌\] enp dot‎ ‌one**. +- To submit an update, please + [fork the repository](https://docs.github.com/en/enterprise/2.20/user/github/getting-started-with-github/fork-a-repo) + and [open a pull request](https://github.com/enpaul/peewee-plus/compare). + +Developing this project requires at least [Python 3.7](https://www.python.org/downloads/) +and at least [Poetry 1.0](https://python-poetry.org/docs/#installation). GNU Make can +optionally be used to quickly setup a local development environment, but this is not +required. + +To setup a local development environment: + +```bash +# Clone the repository... +# ...over HTTPS +git clone https://github.com/enpaul/peewee-plus.git +# ...over SSH +git clone git@github.com:enpaul/peewee-plus.git + +cd peewee-plus/ + +# Create and configure the local dev environment +make dev + +# See additional make targets +make help +```