|
|
# AURWeb Python Port
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
**TO BE WRITTEN**
|
|
|
|
|
|
## Docker Build
|
|
|
|
|
|
If you want to build the project and see its test run with docker, you can run `docker build </path/to/aurweb>` which should result in a full test run of both legacy *sharness* and our new *pytest* suites. At the end, it'll produce a text coverage report of the executed tests.
|
|
|
|
|
|
## State of Development
|
|
|
|
|
|
<small>*This section should be updated when any lists are updated to reflect any changes that may be inconsistent.*</small>
|
|
|
|
|
|
At this point in time (2021-05-08), we have completed the following tasks.
|
|
|
|
|
|
- Introduced the `pytest` framework, which we will be using from now on to test Python code
|
|
|
- Introduced coverage reporting to the project
|
|
|
- Implement language translation management
|
|
|
- Ported over `home.php` (not completely, but the skeleton which needs to be completed)
|
|
|
|
|
|
There is more work underway which is soon to be merged in, listed below.
|
|
|
|
|
|
- User authentication
|
|
|
- Ported over `register.php`
|
|
|
- Ported over `login.php`
|
|
|
- Ported over `logout.php`
|
|
|
- Ported over `passreset.php`
|
|
|
- Ported over `account.php`'s GET of a single user
|
|
|
|
|
|
After authentication efforts are merged in, we can continue onto implementing a `Package` and relevant routes.
|
|
|
|
|
|
If you wish to take on any of these subtasks or porting tasks, please comment in its GitLab issue. You can also contact kevr directly at [kevr@0cost.org](mailto:kevr@0cost.org) or IRC on Freenode with the `kevr` nick if you wish.
|
|
|
|
|
|
**NOTE:** For this porting effort, GitLab is essentially deprecating the `aur-dev` mailing list for communication.
|
|
|
|
|
|
## Subtasks
|
|
|
|
|
|
- [x] Implement `i18n` international language translation
|
|
|
- [x] Create `User` SQLAlchemy ORM model
|
|
|
- [x] Implement `User` authentication
|
|
|
- Awaiting merge.
|
|
|
- [ ] Create `Package` SQLAlchemy ORM model
|
|
|
|
|
|
## Route Porting Tasks
|
|
|
|
|
|
- [ ] 404.php
|
|
|
- [ ] 503.php
|
|
|
- [x] account.php - Waiting merge.
|
|
|
- [ ] addvote.php
|
|
|
- [ ] comaintainers.php
|
|
|
- [ ] commentedit.php
|
|
|
- [x] home.php
|
|
|
- [x] index.php
|
|
|
- [x] login.php - Waiting merge.
|
|
|
- [x] logout.php - Waiting merge.
|
|
|
- [ ] packages.php
|
|
|
- [x] passreset.php - Waiting merge.
|
|
|
- [ ] pkgbase.php
|
|
|
- [ ] pkgdel.php
|
|
|
- [ ] pkgdisown.php
|
|
|
- [ ] pkgflagcomment.php
|
|
|
- [ ] pkgflag.php
|
|
|
- [ ] pkgmerge.php
|
|
|
- [ ] pkgreq.php
|
|
|
- [x] register.php - Waiting merge.
|
|
|
- [ ] rpc.php
|
|
|
- [ ] rss.php
|
|
|
- [ ] tos.php
|
|
|
- [ ] tu.php
|
|
|
- [ ] voters.php
|
|
|
|
|
|
|
|
|
## Getting Familiar
|
|
|
|
|
|
The Python 3 port of this project uses a few frameworks and tools to make life easier for developers and provide modern tooling. Some may be unfamiliar with these packages and modules, and so, here, we attempt to provide pointers to all of them. Below, you will find a listing of our chosen technologies, each with a small description and some links to getting started with them and references where possible.
|
|
|
|
|
|
* FastAPI - [https://fastapi.tiangolo.com](https://fastapi.tiangolo.com)
|
|
|
* A Flask-like, more lightweight HTTP framework.
|
|
|
* SQLAlchemy - [https://www.sqlalchemy.org](https://www.sqlalchemy.org)
|
|
|
* A database connector library for Python.
|
|
|
* SQLAlchemy ORM - [https://docs.sqlalchemy.org/en/13/orm](https://docs.sqlalchemy.org/en/13/orm)
|
|
|
* [**O**]bject [**R**]elational [**M**]apping tools which allow a developer to represent database tables with Python objects.
|
|
|
* Alembic - [https://alembic.sqlalchemy.org/en/latest](https://alembic.sqlalchemy.org/en/latest/)
|
|
|
* A database instrumentation tool used to initialize databases and apply [migrations](https://some_link) to them.
|
|
|
* Jinja2 - [https://jinja.palletsprojects.com/en/2.11.x](https://jinja.palletsprojects.com/en/2.11.x)
|
|
|
* A template framework which we use to generate HTML files. Jinja2 templates allow a developer to use "Python tags" defined which he/she can define in addition to helpful built-ins.
|
|
|
* Requests - [https://docs.python-requests.org/en/master](https://docs.python-requests.org/en/master)
|
|
|
* An HTTP client library used to perform requests in a simple way.
|
|
|
* Bcrypt - [https://github.com/pyca/bcrypt](https://github.com/pyca/bcrypt)
|
|
|
* A crypto library used for aurweb internal passwords and password salts.
|
|
|
* LXML - [https://lxml.de](https://lxml.de)
|
|
|
* An XML-interfacing library, which also supports HTML and allows us to perform xpath searches. This library is typically used to scrape HTML webpages.
|
|
|
* Pytest - [https://docs.pytest.org/en/6.2.x](https://docs.pytest.org/en/6.2.x)
|
|
|
* A test framework for Python.
|
|
|
* Pytest-cov - [https://github.com/pytest-dev/pytest-cov](https://github.com/pytest-dev/pytest-cov)
|
|
|
* A module used to collect and report coverage from Python execution.
|
|
|
|
|
|
Some modules required by legacy code include the following.
|
|
|
|
|
|
* Pygit2 - [https://github.com/libgit2/pygit2](https://github.com/libgit2/pygit2)
|
|
|
* A git interface for Python.
|
|
|
* Srcinfo - [https://github.com/kyrias/python-srcinfo](https://github.com/kyrias/python-srcinfo)
|
|
|
* .SRCINFO parsing library for Arch Linux packages.
|
|
|
* Markdown - [https://python-markdown.github.io](https://python-markdown.github.io)
|
|
|
* Used to display markdown.
|
|
|
* Bleach - [https://github.com/mozilla/bleach](https://github.com/mozilla/bleach)
|
|
|
* HTML sanitization.
|
|
|
|
|
|
Additionally, this project uses the following programs to orchestrate development and/or production.
|
|
|
|
|
|
* hypercorn - [https://gitlab.com/pgjones/hypercorn](https://gitlab.com/pgjones/hypercorn)
|
|
|
* An HTTP/2 compliant ASGI server application. This can be upstreamed in an `nginx` configuration to host the application publicly.
|
|
|
|
|
|
## Contribution Guidelines
|
|
|
|
|
|
All contributions **must** maintain 100% test coverage over any newly added or modified
|
|
|
source code.
|
|
|
|
|
|
Test coverage can be maintained by writing `pytest` units that exercise all paths in
|
|
|
the code that your commits affect.
|
|
|
|
|
|
## Who, Where
|
|
|
|
|
|
**Looking for the code?**
|
|
|
- FastAPI Specific Branch: **pu_fastapi** (based on **pu**)
|
|
|
- https://gitlab.archlinux.org/archlinux/aurweb/-/tree/pu_fastapi
|
|
|
- Upstream Development Branch: **pu**
|
|
|
- https://gitlab.archlinux.org/archlinux/aurweb/-/tree/pu
|
|
|
|
|
|
**Want to chat?**
|
|
|
- Come talk with us in IRC on **Freenode** in the **#archlinux-aurweb** channel
|
|
|
- Note: You must be registered with NickServ to join
|
|
|
|
|
|
**A little anti-social?**
|
|
|
- You can email [kevr](https://gitlab.archlinux.org/kevr) directly at [kevr@0cost.org](mailto:kevr@0cost.org)
|
|
|
|
|
|
## Filing Bugs
|
|
|
|
|
|
We are slowly relocating over to [GitLab](https://gitlab.archlinux.org/archlinux/aurweb), as the original Arch Linux bugtracker, bugs.archlinux.org, is moving toward deprecation.
|
|
|
|
|
|
If you found a bug, have a feature request or general issue with the port (and/or project in general), please create an issue in the new [GitLab repository](https://gitlab.archlinux.org/archlinux/aurweb). This location will be the most active as far as the Python port is concerned. |
|
|
\ No newline at end of file |