decimaldate

general
docs
code
package
downloads

About

Python decimal date utility to handle integer dates on the form yyyymmdd.

Creation

No argument or None

Will use today's date:

DecimalDate()
DecimalDate(None)

are equivalent.

int

>>> from decimaldate import DecimalDate
>>> DecimalDate(20240911)
DecimalDate(20240911)

str

>>> from decimaldate import DecimalDate
>>> DecimalDate("20240911")
DecimalDate(20240911)

decimaldate

>>> from datetime import datetime
>>> DecimalDate(datetime.today()) == DecimalDate.today()
True

Functionality

There are computational and utillity/ convenience class and instance methods to make use of DecimalDate including a range().

Please see the latest documentation and the usage page.

As an example loop over all Tuesdays in the month of Valentine's Day 2024.

>>> from decimaldate import DecimalDateRange
>>>
>>> TUESDAY = 1
>>>
>>> for dd in [
>>>     dd
>>>     for dd in DecimalDateRange.range_month_of_decimal_date(2024_02_14)
>>>     if dd.weekday() == TUESDAY
>>> ]:
>>>     print(repr(dd))
DecimalDate(20240206)
DecimalDate(20240213)
DecimalDate(20240220)
DecimalDate(20240227)

Introduction

The source for this decimaldate project is publicly available on GitHub (here).

Note

This project and the development of the module decimaldate is documented here, in this README.rst file.

The Python decimaldate package itself, and its use, is documented in the project's docs/source as reStructuredText to be processed with Sphinx and made available on readthedocs as decimaldate.

Setup for Development

Use a virtual environment

It is optional, but highly recommended (and best practice) to create and use a virtual environment.

This documentation will assume the use of a virtual environment and venv (handled if you use make and the supplied Makefile).

python3 -m venv venv

Note

You can use other virtualization tools as you prefer.

You can choose another name than venv, but the Makefile makes this assumption.

Activate (source) the virtual environment (remember the . activation).

. venv/bin/activate

Note

This will activate for macOS and Linux.

For Windows CMD or PowerShell run the activation scripts instead.

Install requirements

Install requirements and their dependencies for development (which are not deployment dependencies).

. venv/bin/activate
python3 -m pip install --upgrade -r requirements/development.txt

Build and Test

Remember activation of the virtual environment.

Build

Build (where the pyproject.toml file is located):

python3 -m build

Install updated project with editing (remember the .):

python3 -m pip install --upgrade -e .

Test

Test:

pytest

Coverage:

Note

My personal preference is to use coverage as is, and not the extension for pytest pytest-cov (see pytest-cov).

coverage run -m pytest tests

Make run coverage into report:

coverage report -m

The coverage will generate a .coverage file, which can be shared, used by other tools, or be used to make a coverage report.

Make run coverage into report as HTML:

coverage html

To see the HTML report, open the default location: htmlcov/index.html in a browser and/or lightweight http server.

. venv/bin/activate
coverage run -m pytest tests
coverage report -m
coverage html
# macOS
open htmlcov/index.html

Building the Documentation

Activate the virtual environment and run Sphinx (similar to how readthedocs builds).

. venv/bin/activate
cd docs
make html
# macOS
open build/html/index.html

To see the output documentation, open in a browser and/or lightweight http server.

Upload to PyPI

Make sure you have build beforehand, so the latest (and only the latest) version is in the dist directory. If you use make build the dist directory will be emptied before building.

Note

You will need twine installed; which is part of the development requirements file.

python3 -m twine upload --verbose --repository pypi dist/*

You will be asked for your API token:

See Packaging Python Projects for more information.

Note

If you see:

400 The description failed to render for 'text/x-rst'.

See https://pypi.org/help/#description-content-type for more information.

You may have put Sphinx specifics into the plain reStructuredText that PyPI wants.

See rstcheck for a linter to help you fix markup problems.

Comments

The earlier mentioned commands are available as make targets in the included Makefile.

make setup

will create the virtual environment and install dependencies.

The chosen version of Python for make targets in the Makefile is 3.11, which must be present on the development environment. The choice for the development environment to stay at 3.11 is made to minimize the risk of breaking code and keep backward compatibility.

Additionally the creation of documentation using Sphinx currently have a dependency on packages not released for 3.12 or later. If you are not interested in building documentation (by leaving that solely to readthedocs) you can update the Makefile to any Python version >= 3.11. The module has been built and unit tested with: 3.11, 3.12, and 3.13.

Documentation

To build the documentation go to the docs directory and work with the reStructuredText (.rst) files and Sphinx.

Use the make command to see options for documentation build using Sphinx.

When ready update documentation on readthedocs.

Remember to have tagged source/release and pushed to GitHub.

It is highly recommended to test the update by uploading to https://test.pypi.org/ before updating PyPI.

Locally you can run make html to see the generated output, and rstcheck to validate and lint your markup.

Tools

Note

At some later date I will replace some of the tooling with ruff.

python3

Of course...

See Python.

pip

The package installer for Python.

Use pip to install packages from PyPI or other indexes.

See pip.

flake8

A Python linting tool for style guide enforcement.

See flake8.

black

Part of my vscode installation.

See black.

mypy

A static type checker for Python (type hints are optional and not enforced).

See mypy.

pytest

From the documentation:

The pytest framework makes it easy to write small, readable tests, and can scale to support complex functional testing for applications and libraries.

See pytest.

coverage

From the documentation:

Coverage.py is a tool for measuring code coverage of Python programs. It monitors your program, noting which parts of the code have been executed, then analyzes the source to identify code that could have been executed but was not.

My personal preference is to use coverage as is, and not the extension for pytest pytest-cov (see pytest-cov).

See coverage.

sphinx

To generate local copy of documentation meant for readthedocs.

The theme chosen is Read The Docs (the default is Alabaster).

See Sphinx.

readthedocs

A site building and hosting documentation.

Sign up for a free account if you qualify (FOSS). The free account has a limit on concurrent builds (think GitHub actions and CI/CD) and displays a tiny advertisement (see readthedocs-community).

See readthedocs.

rstcheck

Lints your reStructuredText markdown files.

From the documentation:

Checks syntax of reStructuredText and code blocks nested within it.

The shown warnings/errors are benign and are caused by the autogeneration of links for sections. As some sections have the same name, this is flagged. These particular warnings I will ignore.

See rstcheck.

Outstanding

• None.