fixes sqlalchemy deprecation warning, docstrings

.github/workflows/tox.yml

@@ -0,0 +1,25 @@
+name: tox
+
+on:
+  pull_request:
+  workflow_dispatch:  # you can trigger this workflow manually
+
+jobs:
+  tox_on_ubuntu:
+
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        python: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+      - name: install tox
+        run: pip install tox
+      - name: run tox
+        # Run tox using the version of Python in `PATH`
+        run: tox -e py

.gitignore

@@ -17,6 +17,9 @@ __pycache__/
 *.pdf
 *.svg
 
+# experimental code:
+experimental/
+
 # Mac OS
 .DS_Store
 
@@ -26,7 +29,3 @@ htmlcov/
 
 # due to vscode:
 .vscode/
-
-# other
-bug_reports/
-experimental/

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Code of Conduct
+
+Everyone interacting in this project is expected to follow the [PSF Code of
+Conduct]. This includes all infrastructure used in the development, such as
+codebases, issue trackers, chat rooms, and mailing lists.
+
+In general, this means that everyone is expected to be **open**,
+**considerate**, and **respectful** of others no matter what their position is
+within the project.
+
+
+## Reporting
+
+All incidents should be reported by emailing github@tambora.ch.
+
+[PSF Code of Conduct]: https://www.python.org/psf/conduct/

docs/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# How to contribute
+
+Thank for considering a contribution! Any help is greatly appreciated.
+
+
+## Did you find an issue?
+
+* Check whether your issue has already been reported by searching under
+  [existing issues](https://github.com/adrianschlatter/ppf.jabref/issues).
+
+* If don't find an issue addressing the problem, open a new issue.
+
+* Choose a meaningful title, describe clearly what you consider to be a
+  problem.
+
+* If possible, provide example code or other means to make it easy for a
+  maintainer to reproduce your problem.
+
+
+## Contributing Code
+
+You want to help with a bug or contribute a new feature? The [development
+docs](./dev/DEV_DOCS.md) might help you along.
+
+You already have a solution for an issue or a new feature? All the better! A
+pull request ("PR") is what you want to do.
+
+* Open a new [pull-request](https://github.com/adrianschlatter/ppf.jabref/pulls)
+  with your patch.
+
+* Try to create PRs that address a specific issue/feature/topic.
+
+* Avoid PRs containing an assortment of unrelated fixes and features. Better
+  split it into separate PRs for each topic.
+
+* Clean up your code before creating a pull request: Remove code that you have
+  commented out for debugging, remove test code you have added.
+
+* Make sure the PR's description clearly describes the problem and your
+  solution. Include relevant issue numbers if appropriate.
+
+* You increase the chances of quick acceptance of your PR significantly if you
+  have taken measures to assure quality (such as writing and passing tests).
+
+
+## Final remarks
+
+Currently, this project is maintained in the spare time of a single person
+having a family and a job. If you do not get immediate feedback to your issue
+or pull request, please have some patience.

docs/README.md

@@ -1,5 +1,7 @@
 # ppf.jabref
 
+<img alt="pypi downloads/month" src="https://img.shields.io/pypi/dm/ppf.jabref.svg">
+
 ppf.jabref provides a [python](https://www.python.org) interface to
 [JabRef](https://www.jabref.org) SQL databases. It maps database relations
 to python classes using [SQLAlchemy](https://www.sqlalchemy.org).
@@ -66,3 +68,37 @@ the database connection. The query then uses ppf.jabref's Entry class to
 obtain all Entries (=references) in the JabRef database. The for-loop
 shows how to access fields and uses the File class to find out where the
 documents linked to this entry are stored.
+
+
+## Installation
+
+ppf.jabref is available via [pypi](https://pypi.org):
+
+```
+pip install ppf.jabref
+```
+
+
+## Still reading?
+
+If you read this far, you're probably not here for the first time. If you use
+and like this project, would you consider giving it a Github Star? (The button
+is at the top of this website.) If not, maybe you're interested in one of
+[my other projects](https://github.com/adrianschlatter/ppf.sample/blob/develop/docs/list_of_projects.md)?
+
+
+## Contributing
+
+Did you find a bug and would like to report it? Or maybe you've fixed it
+already or want to help fixing it? That's great! Please read
+[CONTRIBUTING](./CONTRIBUTING.md) to learn how to proceed.
+
+To help ascertain that contributing to this project is a pleasant experience,
+we have established a [code of conduct](./CODE_OF_CONDUCT.md). You can expect
+everyone to adhere to it, just make sure you do as well.
+
+
+## Change Log
+
+* 0.1.1: Fix sqlalchemy deprecation warning, docstrings
+* 0.1.0: Initial release

docs/README_pypi.md

@@ -42,3 +42,18 @@ the database connection. The query then uses ppf.jabref's Entry class to
 obtain all Entries (=references) in the JabRef database. The for-loop
 shows how to access fields and uses the File class to find out where the
 documents linked to this entry are stored.
+
+
+## Installation
+
+ppf.jabref is available via [pypi](https://pypi.org):
+
+```
+pip install ppf.jabref
+```
+
+
+## Change Log
+
+* 0.1.1: Fix sqlalchemy deprecation warning, docstrings
+* 0.1.0: Initial release

docs/dev/DEV_DOCS.md

@@ -0,0 +1,29 @@
+# Development Docs
+
+This is the top-level development document. It provides an overview and links
+to more specific documents.
+
+
+## Getting Started
+
+To start developing, you will need:
+
+```
+pip install .[test]
+pip install .[dev]
+```
+
+(Note: Depending on your shell, you might need to escape '[' and ']'.)
+
+
+## Packaging
+
+This package inherits its structure, build- and distribution "mechanics"
+from [ppf.sample](https://github.com/adrianschlatter/ppf.sample). And
+improvements gained with this package are also meant to flow back into said
+template project.
+
+
+## Release Process
+
+"[Release-Process](./release-process.md)" describes how we do a release.

docs/dev/release_process.md

@@ -0,0 +1,82 @@
+# Release Process
+
+Make sure that you:
+
+* updated the changelog (/docs/README.md)
+* checked the README for pypi (/docs/README_pypi.md)
+
+
+## Pull-Request into master
+
+* Push changes to Github
+* Create PR into master
+* Github will run workflows (tox in our case)
+* Merge PR when all is well (merge commit, not squash or fast forward)
+
+A commit in master is a release. Pull the new commit and tag it:
+
+```shell
+git checkout master
+git tag vX.Y.Z
+```
+
+Then push the tag back to Github:
+
+```shell
+git push origin vX.Y.Z
+```
+
+Tagging is important because the version of the package we are going to build
+is derived from this tag.
+
+
+## Build
+
+From the root of the project folder, run
+
+```
+python3 -m build --wheel
+```
+
+This generates a wheel distribution in /dist.
+
+## Test-pypi
+
+Upload to test.pypi.org by (make sure the '*' selects only your package):
+
+```
+twine upload -r testpypi dist/*
+```
+
+Note: Your `~/.pypirc` has to specify a `[testpypi]` section providing your
+username and password.
+
+
+## pypi
+
+If everything worked as expected, run
+
+```
+twine upload dist/*
+```
+
+Note: Your `~/.pypirc` has to specify a `[pypi]` section providing your
+username and password.
+
+## Test Install
+
+Activate an environment that does not have a (development-) installation of
+this package. Run
+
+```
+pip install ppf.jabref
+```
+
+This should download and install the version you've just released.
+
+
+## GitHub
+
+Finally, go to github, find the new tag, click the ellipsis, click
+"create release". Enter the tag name as title and copy the commit message
+into the description.

pyproject.toml

@@ -1,5 +1,3 @@
 [build-system]
-# These are the assumed default build requirements from pip:
-# https://pip.pypa.io/en/stable/reference/pip/#pep-517-and-518-support
-requires = ["setuptools>=40.8.0", "wheel"]
+requires = ["setuptools", "setuptools-scm"]
 build-backend = "setuptools.build_meta"