docs: add CONTRIBUTING.md and update LICENSE, README.md

.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

.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.")

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`.

LICENSE

@@ -1 +1,19 @@
-Copyright (c) 2022 Uwe Stuehler <ustuehler@bsdx.de>
+Copyright (c) 2022 Uwe Stuehler <uwe@bsdx.de>
+
+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.

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)

pyproject.toml

@@ -6,16 +6,16 @@ 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"
 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]