From 6f97ff74e0c3d1804459f2c9f344b3e500d2434e Mon Sep 17 00:00:00 2001 From: Ethan Paul <24588726+enpaul@users.noreply.github.com> Date: Thu, 13 Apr 2023 13:34:37 -0400 Subject: [PATCH] Fix documentation errors Add more links to external docs where appropriate Fix readme links hardcoded to github and 1.0.0 tag Clarify intended usage of the calc_batch_size function --- README.md | 27 +++++++++++++-------------- peewee_plus.py | 15 ++++++++++----- 2 files changed, 23 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 55f7905..f0ba2bd 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ release history. ## Installing -Peewee+ is [available on PyPI](https://pypi.org/project/peewee-plus/) and can be installed +peewee+ is [available on PyPI](https://pypi.org/project/peewee-plus/) and can be installed using Poetry, Pipenv, or Pip: ```bash @@ -57,30 +57,29 @@ when using SQLite ### Functions -[`calc_batch_size`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L71) - -Helper function for determining how to batch a create/update query with SQLite +[`calc_batch_size`](blob/devel/peewee_plus.py#L75) - Helper function for writing +backend-agnostic batch queries while accounting for the +[SQLite max variable limit](https://www.sqlite.org/limits.html#max_variable_number). -[`flat_transaction`](https://github.com/enpaul/peewee-plus/blob/devel/peewee_plus.py#L137) -\- Decorator function for wrapping callables in a database transaction without creating -nested transactions +[`flat_transaction`](blob/devel/peewee_plus.py#L141) - Decorator function for wrapping +callables in a database transaction without creating nested transactions ### Classes -[`PathField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#179) - A -Peewee database field for storing +[`PathField`](blob/devel/peewee_plus.py#186) - 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#L237) -\- A Peewee database field for storing floats while specifying the +[`PrecisionFloatField`](blob/devel/peewee_plus.py#L244) - 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#L267) - A -Peewee database field for storing arbitrary JSON-serializable data +[`JSONField`](blob/devel/peewee_plus.py#L275) - A Peewee database field for storing +arbitrary JSON-serializable data -[`EnumField`](https://github.com/enpaul/peewee-plus/blob/1.0.0/peewee_plus.py#L322) - A -Peewee database field for storing Enums by name +[`EnumField`](blob/devel/peewee_plus.py#L330) - A Peewee database field for storing Enums +by name ## For Developers diff --git a/peewee_plus.py b/peewee_plus.py index 834737a..46a86ef 100644 --- a/peewee_plus.py +++ b/peewee_plus.py @@ -1,4 +1,6 @@ -"""Peewee+ +"""peewee+ + +Various extensions, helpers, and utilities for `Peewee`_ :constant SQLITE_DEFAULT_VARIABLE_LIMIT: The default number of variables that a single SQL query can contain when interfacing with SQLite. The actual @@ -10,7 +12,9 @@ SQLite database connection. The value for this constant is taken directly from the `Peewee documentation`_ -.. _`Peewee documentation`: http://docs.peewee-orm.com/en/latest/peewee/database.html#recommended-settings +.. _`Peewee`: https://docs.peewee-orm.com/en/latest/ + +.. _`Peewee documentation`: https://docs.peewee-orm.com/en/latest/peewee/database.html#recommended-settings """ import contextlib import enum @@ -254,8 +258,9 @@ class PrecisionFloatField(peewee.FloatField): # pylint: disable=abstract-method .. _here: https://stackoverflow.com/a/67476045/5361209 :param max_digits: Maximum number of digits, combined from left and right of the decimal place, - to store for the value. - :param decimal_places: Maximum number of digits that will be stored after the decimal place + to store for the value; corresponds to the ``M`` MySQL precision parameter. + :param decimal_places: Maximum number of digits that will be stored after the decimal place; + corresponds to the ``D`` MySQL precision parameter. """ def __init__(self, *args, max_digits: int = 10, decimal_places: int = 4, **kwargs): @@ -270,7 +275,7 @@ class PrecisionFloatField(peewee.FloatField): # pylint: disable=abstract-method class JSONField(peewee.TextField): # pylint: disable=abstract-method """Field class for storing JSON-serializable data - This field can be used to store a dictionary of data directly in the database without needing + This field can be used to store a dictionary of data directly in the database without needing to call :func:`json.dumps` and :func:`json.loads` directly. ::