From ac60e9a7faafe23b95d41f6bf1bddd04fbd39e1e Mon Sep 17 00:00:00 2001 From: Uwe Stuehler Date: Wed, 28 Sep 2022 20:19:45 +0900 Subject: [PATCH] docs: add CONTRIBUTING.md and update LICENSE, README.md --- .envrc | 23 +++++++----- .pythonrc | 9 +++-- CONTRIBUTING.md | 35 ++++++++++++++++++ LICENSE | 20 ++++++++++- README.md | 95 ++++++++++++++----------------------------------- pyproject.toml | 4 +-- 6 files changed, 102 insertions(+), 84 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.envrc b/.envrc index 0794221..15f82b2 100644 --- a/.envrc +++ b/.envrc @@ -1,13 +1,18 @@ -if [[ -z $VIRTUAL_ENV ]]; then - if [[ ! -d .venv ]]; then - python3 -m venv .venv - fi +source_up +if [[ -z $VIRTUAL_ENV ]]; then + python3 -m venv .venv source ./.venv/bin/activate fi -if [[ -z $PYTHONSTARTUP ]]; then - export PYTHONSTARTUP="$PWD/.pythonrc" -else - echo "warning: PYTHONSTARTUP is already defined; ignoring .envrc value" -fi +pip install -r requirements.txt + +echo "Start Python via \`python -i .pythonrc\` to explore this package." + +if [[ -z $JPDB_USERNAME ]] && [[ -z $JPDB_PASSWORD ]]; then + if [[ -n $JPDB_GOPASS_PATH ]]; then + JPDB_USERNAME="$(gopass show -o "$JPDB_GOPASS_PATH" "${JPDB_GOPASS_ATTR_USERNAME:-username}")" + JPDB_PASSWORD="$(gopass show -o "$JPDB_GOPASS_PATH")" + export JPDB_USERNAME JPDB_PASSWORD + fi +fi \ No newline at end of file diff --git a/.pythonrc b/.pythonrc index f038c92..bbd0d77 100644 --- a/.pythonrc +++ b/.pythonrc @@ -5,13 +5,16 @@ import json from jpdb import JPDB from jpdb.export.reviews import Reviews -jpdb = JPDB(os.environ['JPDB_USERNAME'], os.environ['JPDB_PASSWORD']) +if 'JPDB_USERNAME' in os.environ and 'JPDB_PASSWORD' in os.environ: + jpdb = JPDB(os.environ['JPDB_USERNAME'], os.environ['JPDB_PASSWORD']) -print(f"Type \"help(jpdb)\" to learn about the jpdb.io client.") + print(f"Type \"help(jpdb)\" to explore the jpdb.io client.") +else: + print(f"Type \"help(JPDB)\" to explore the jpdb.io client.") fixtures_dir = os.path.join(os.path.dirname(__file__), 'tests', 'fixtures') with open(os.path.join(fixtures_dir, 'reviews.json')) as f: reviews = Reviews(json.loads(f.read())) -print(f"Type \"help(reviews)\" to learn about working with exported reviews.") +print(f"Type \"help(reviews)\" to explore exported reviews.") diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..789b5bd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,35 @@ +# Contributing Guide + +For now, this is a personal project and I don't have any plans to support it, +at least not until there's an official API documentation available for jpdb. + +## Getting started with local development + +These instructions assume that [Python 3](https://docs.python.org/3/) is +installed in your system and available in the shell's command search path as +`python3`. + +Once you have cloned this repository, create and activate a temporary virtual +environment, and then install the required dependencies as follows: + +``` +python3 -m venv .venv +. ./.venv/bin/activate +pip install -r requirements.txt +``` + +[Register](https://jpdb.io/register) a jpdb user account, unless you already +have one, and then provide its username and password as environment variables: + +``` +export JPDB_USERNAME='your_username' +export JPDB_PASSWORD='your_password' +``` + +You can then start Python via `python -i .pythonrc` to explore the functionality +and documentation of this package interactively. + +## Running unit and integration tests locally + +Ensure that the temporary virtual environment created for local development is +active, and then execute the command `python -m unittest`. diff --git a/LICENSE b/LICENSE index 9e27e32..ef36b55 100644 --- a/LICENSE +++ b/LICENSE @@ -1 +1,19 @@ -Copyright (c) 2022 Uwe Stuehler +Copyright (c) 2022 Uwe Stuehler + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, +DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR +OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE +OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index aba1db3..04a327c 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,58 @@ # py-jpdb -An Python 3 package providing an experimental client for the [jpdb](https://jpdb.io/) service. -## Dependencies +A Python 3 package providing a _very_ limited and experimental client for [jpdb](https://jpdb.io/), a powerful Japanese dictionary and all-in-one learning system. -### Development - -- [Python 3](https://docs.python.org/3/) - -Optionally: - -- [direnv](https://direnv.net/) - -### Runtime - -- [Python 3](https://docs.python.org/3/) -- [Active jpdb account](https://jpdb.io/login) +## Features -## Installation +- Validation of login credentials (`JPDB.login`) +- Get the total number of due items (`JPDB.due_items`) +- Export the entire review history (`JPDB.reviews`) -Put the following line in `requirements.txt` or pass it as an argument to [pip](https://pip.pypa.io/en/stable/)'s `install` command: +## Installation with pip ``` -git+ssh://git@github.com/ustuehler/py-jpdb@main +pip install git+https://github.com/ustuehler/py-jpdb ``` -However, you _should_ specify the [latest release](https://github.com/ustuehler/py-jpdb/releases/latest) version instead of `main` and upgrade manually as needed. - ## Usage +You need an active user account on jpdb in order to use this client, and you +must [register](https://jpdb.io/register) with username and password instead of +using the "Sign in with Google" option. + +Example: + ```python -from jpdb import JPDB import os +from jpdb import JPDB +# Get the username and password from somewhere (NB: OAuth is not supported) username = os.environ['JPDB_USERNAME'] password = os.environ['JPDB_PASSWORD'] +# Create a jpdb client instance jpdb = JPDB(username, password) # Ensure that credentials are valid (optional) jpdb.login() -# Do something useful, for example: +# Do something useful print(jpdb.due_items) ``` -## Features - -- `login()`: Validation of login credentials (username & password) -- `due_items`: Get the total number of due items (vocabulary and Kanji cards combined) -- `reviews`: Export the review history for each type of card (vocabulary and Kanji, forward and reverse) - -## Roadmap - -- Experimental functionality implemented by scraping the web interface -- Official API client once jpdb publishes their API documentation - -## Development - -To start an interactive Python interpreter with the [jpdb](src/jpdb) package -already imported and an instance of the `JPDB` class available as `jpdb`: - -```bash -python3 -m venv .venv -source ./.venv/bin/activate - -export PYTHONPATH="$PWD/src" -export PYTHONSTARTUP="$PWD/.pythonrc" - -export JPDB_USERNAME=... -export JPDB_PASSWORD=... - -python -``` - -## Testing - -To execute all unit and integration tests: - -```bash -python3 -m venv .venv -source ./.venv/bin/activate - -export PYTHONPATH="$PWD/src" -export PYTHONSTARTUP="$PWD/.pythonrc" - -env JPDB_USERNAME=yourname \ - JPDB_PASSWORD=secret \ - python -m unittest -``` +For other possible usages, please see the implementation of the `JPDB` class in +[jpdb/\_\_init\_\_.py](jpdb/__init__.py). ## Changes -All notable changes in this project will be documented in the file +All notable changes to this project will be documented in the file [CHANGELOG.md](CHANGELOG.md). -## License +## Contributing + +See the [Contributing Guide](CONTRIBUTING.md) for instructions on how to set up +a local environment for development and testing. -[//]: # (TODO: select a license, audit, and publish the package on PyPi) +## License -[Copyright © 2022 Uwe Stuehler (UNLICENSED)](LICENSE) +[MIT](LICENSE) diff --git a/pyproject.toml b/pyproject.toml index 1389373..eb6e9a0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta" name = "jpdb" version = "0.3.1" authors = [ - { name="Uwe Stuehler", email="ustuehler@bsdx.de" }, + { name="Uwe Stuehler", email="uwe@bsdx.de" }, ] description = "An experiemental client for jpdb.io" readme = "README.md" @@ -14,8 +14,8 @@ requires-python = ">=3.9" dynamic = ["dependencies"] classifiers = [ "Programming Language :: Python :: 3", - #"License :: OSI Approved :: MIT License", "Operating System :: OS Independent", + "License :: OSI Approved :: MIT License", ] [project.urls]