From 1d995f24624211ee87b9b6719c922a14f66064a6 Mon Sep 17 00:00:00 2001 From: s3lph Date: Wed, 13 Jun 2018 00:52:47 +0200 Subject: [PATCH] Added some more documentation, especially package docs. --- README.md | 31 +++++++++++++++++++++----- matemat/db/__init__.py | 3 +++ matemat/db/test/test_facade.py | 1 + matemat/db/test/test_wrapper.py | 1 + matemat/exceptions/__init__.py | 3 +++ matemat/primitives/__init__.py | 3 +++ matemat/webserver/__init__.py | 7 ++++++ matemat/webserver/httpd.py | 3 ++- matemat/webserver/pagelets/__init__.py | 5 +++++ 9 files changed, 51 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 8082659..80b8d89 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,22 @@ -# matemat +# Matemat -[![pipeline status](https://gitlab.com/s3lph/matemat/badges/master/pipeline.svg)](https://gitlab.com/s3lph/matemat/commits/master) -[![coverage report](https://gitlab.com/s3lph/matemat/badges/master/coverage.svg)](https://gitlab.com/s3lph/matemat/commits/master) +[![pipeline status](https://gitlab.com/s3lph/matemat/badges/master/pipeline.svg)][master] +[![coverage report](https://gitlab.com/s3lph/matemat/badges/master/coverage.svg)][master] + +A web service for automated stock-keeping of a soda machine written in Python. +It provides a touch-input-friendly user interface (as most input happens through the +soda machine's touch screen). + +This project intends to provide a well-tested and maintainable alternative to +[TODO][todo] (discontinued). + +## Further Documentation + +[Wiki][wiki] ## Dependencies -- Python 3.6 +- Python 3 (>=3.6) - Python dependencies: - apsw - bcrypt @@ -16,6 +27,16 @@ python -m matemat ``` +## Contributors + +- s3lph +- SPiNNiX + ## License -[MIT License](https://gitlab.com/s3lph/matemat/blob/master/LICENSE) +[MIT License][mit-license] + + +[mit-license]: https://gitlab.com/s3lph/matemat/blob/master/LICENSE +[master]: https://gitlab.com/s3lph/matemat/commits/master +[wiki]: https://gitlab.com/s3lph/matemat/wiki \ No newline at end of file diff --git a/matemat/db/__init__.py b/matemat/db/__init__.py index 93b6c8c..4f80a25 100644 --- a/matemat/db/__init__.py +++ b/matemat/db/__init__.py @@ -1,3 +1,6 @@ +""" +This package provides a developer-friendly API to the SQLite3 database backend of the Matemat software. +""" from .wrapper import DatabaseWrapper from .facade import MatematDatabase diff --git a/matemat/db/test/test_facade.py b/matemat/db/test/test_facade.py index c266feb..d7236b6 100644 --- a/matemat/db/test/test_facade.py +++ b/matemat/db/test/test_facade.py @@ -10,6 +10,7 @@ from matemat.exceptions import AuthenticationError, DatabaseConsistencyError class DatabaseTest(unittest.TestCase): def setUp(self) -> None: + # Create an in-memory database for testing self.db = MatematDatabase(':memory:') def test_create_user(self) -> None: diff --git a/matemat/db/test/test_wrapper.py b/matemat/db/test/test_wrapper.py index 152066a..dafff65 100644 --- a/matemat/db/test/test_wrapper.py +++ b/matemat/db/test/test_wrapper.py @@ -7,6 +7,7 @@ from matemat.db import DatabaseWrapper class DatabaseTest(unittest.TestCase): def setUp(self) -> None: + # Create an in-memory database for testing self.db = DatabaseWrapper(':memory:') def test_create_schema(self) -> None: diff --git a/matemat/exceptions/__init__.py b/matemat/exceptions/__init__.py index cacbbb9..ebae437 100644 --- a/matemat/exceptions/__init__.py +++ b/matemat/exceptions/__init__.py @@ -1,3 +1,6 @@ +""" +This package provides custom exception classes used in the Matemat codebase. +""" from .AuthenticatonError import AuthenticationError from .DatabaseConsistencyError import DatabaseConsistencyError diff --git a/matemat/primitives/__init__.py b/matemat/primitives/__init__.py index f380d86..a18a142 100644 --- a/matemat/primitives/__init__.py +++ b/matemat/primitives/__init__.py @@ -1,3 +1,6 @@ +""" +This package provides the 'primitive types' the Matemat software deals with - namely users and products. +""" from .User import User from .Product import Product diff --git a/matemat/webserver/__init__.py b/matemat/webserver/__init__.py index bb51b73..f4d86f3 100644 --- a/matemat/webserver/__init__.py +++ b/matemat/webserver/__init__.py @@ -1,2 +1,9 @@ +""" +The Matemat Webserver. + +This package provides the webserver for the Matemat software. It uses Python's http.server and extends it with an event +API that can be used by 'pagelets' - single pages of a web service. If a request cannot be handled by a pagelet, the +server will attempt to serve the request with a static resource in a previously configured webroot directory. +""" from .httpd import MatematWebserver, HttpHandler, pagelet diff --git a/matemat/webserver/httpd.py b/matemat/webserver/httpd.py index e776151..20af55c 100644 --- a/matemat/webserver/httpd.py +++ b/matemat/webserver/httpd.py @@ -16,7 +16,7 @@ from datetime import datetime, timedelta from matemat import __version__ as matemat_version -# Enable IPv6 support (with implicit DualStack) +# Enable IPv6 support (IPv6/IPv4 dual-stack support should be implicitly enabled) TCPServer.address_family = socket.AF_INET6 @@ -25,6 +25,7 @@ _PAGELET_PATHS: Dict[str, Callable[[str, str, Dict[str, str], Dict[str, Any], Di Tuple[int, Union[bytes, str]]]] = dict() +# Inactivity timeout for client sessions _SESSION_TIMEOUT: int = 3600 diff --git a/matemat/webserver/pagelets/__init__.py b/matemat/webserver/pagelets/__init__.py index dabd91d..9b926d6 100644 --- a/matemat/webserver/pagelets/__init__.py +++ b/matemat/webserver/pagelets/__init__.py @@ -1,3 +1,8 @@ +""" +This package contains the pagelet functions served by the Matemat software. + +A new pagelet function must be imported here to be automatically loaded when the server is started. +""" from .main import main_page from .login import login_page