https://github.com/lhelwerd/rechu

Receipt cataloging hub
https://github.com/lhelwerd/rechu

cataloging personal-finance receipts

Last synced: 3 months ago
JSON representation

Receipt cataloging hub

• Host: GitHub
• URL: https://github.com/lhelwerd/rechu
• Owner: lhelwerd
• License: mit
• Created: 2024-11-25T16:06:16.000Z (8 months ago)
• Default Branch: main
• Last Pushed: 2025-03-30T14:49:10.000Z (4 months ago)
• Last Synced: 2025-03-30T15:32:51.151Z (4 months ago)
• Topics: cataloging, personal-finance, receipts
• Language: Python
• Homepage:
• Size: 111 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Receipt cataloging hub

[![Coverage](https://github.com/lhelwerd/rechu/actions/workflows/coverage.yml/badge.svg)](https://github.com/lhelwerd/rechu/actions/workflows/coverage.yml)

[![Coverage Status](https://coveralls.io/repos/github/lhelwerd/rechu/badge.svg?branch=main)](https://coveralls.io/github/lhelwerd/rechu?branch=main)

[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=lhelwerd_rechu&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=lhelwerd_rechu)

This repository contains a Python module that implements a database system for 

reading digitized receipts for detailed product purchases. Currently, the 

receipts and some product metadata have to be written first in YAML files.

The module is written for Python 3.9+ and supported database backends are 

SQLite and PostgreSQL. It is currently in alpha phase and is meant to be 

developed with more features for reporting, external data and so on. Detailed 

information on changes for each version is found in the 

[changelog](CHANGELOG.md) file.

## Installation

Source releases of versions are available from 

[GitHub](https://github.com/lhelwerd/rechu/tags).

When using the source release or if this repository is cloned, then 

installation of the module is possible with `pip install` followed by either 

the release zip/tarball or the current directory. `make install` installs from 

the current directory. We recommend using virtual environments to keep your 

dependencies separate from global installation.

To install a development version of the module as a dependency, use 

`git+https://github.com/lhelwerd/rechu.git@main#egg=rechu` in 

a `requirements.txt` or similar. Other means of specifying a release of the 

module in order to use it as a dependency exists, see [requirements file 

format](https://pip.pypa.io/en/stable/reference/requirements-file-format/) for 

inspiration.

## Running

After installation, the `rechu` command should be available in your environment 

to run various subcommands, but it has not been configured and set up with any 

data sources and database connection.

In order to run the module, first place a `settings.toml` file in the directory 

from which you will use the module, which might be the current directory. 

Either use `rechu config > settings.toml` or (when using the source release or 

if this repository is cloned) copy the example `rechu/settings.toml` file with 

default values to another `settings.toml` file, then edit the new file to 

adjust values in it. If you plan to use this package as a dependency in your 

own module, then you can also override the values in a `pyproject.toml` file 

using `[tool.rechu...]` sections.

To create the database schema in the database path defined in the settings, use 

`rechu create`. Then, you can create receipts with `rechu new`; the new 

receipts are written both to YAML files in the defined path/filename format and 

imported to the database. You can also bulk-import YAML files from the defined 

path and subdirectory pattern with `rechu read`; you can later use the same 

command to synchronize changes in YAML files to the database.

When you install a new version of this package, there may be database schema 

changes which need to be applied to continue using the current model. After 

backing up your database, you should run `rechu alembic upgrade head` to 

migrate your database to the proper version. This command will use the database 

connection configured in your `settings.toml` file.

Some additional scripts that do not use the database are available in the 

`scripts` directory in the repository. These are mostly meant for experiments, 

simple reporting and validation.

## Development and testing

The module is tested with unit tests that are run on pytest. In the repository, 

first install dependencies with `make setup_test`, then run unit tests using 

`make test`. Additionally, obtain coverage information by using `make coverage` 

to perform the unit tests and receive output in the form of a textual report 

and XML report. Finally, an HTML report is obtainable with `coverage html`.

Typing and style checks are also possible by first installing dependencies 

using `make setup_analysis`. Then, use `make mypy` to run the type checker and 

receive HTML and XML reports. Style checks are done by using `make pylint` for 

an aggregate report output.

The unit test coverage, typing coverage, style checks and schema validation is 

combined in one [GitHub Actions](https://github.com/lhelwerd/rechu/actions) 

workflow which is run on commits to the main branch and pull request changes. 

Unit test coverage is then stored for comparative purposes via the interface at 

[Coveralls](https://coveralls.io/github/lhelwerd/rechu). The tests and coverage 

results are combined with analysis results (including typing coverage by Mypy, 

code style checks from Pylint and schema validation) as part of a quality gate 

on [SonarCloud](https://sonarcloud.io/project/overview?id=lhelwerd_rechu).

## License

The module is licensed under the MIT License. See the [license](LICENSE) file 

for more information.