watchful

Watchful Python Package for Interacting with Watchful Environment

Overview

The Watchful Python Package allows installation of the Watchful Python SDK over the internet from PyPI. The Watchful Python SDK enables communication with the Watchful API using Python and helps in the automation of Watchful Python features when used with the product.

The current features include the following and their corresponding user guides:

• Watchful API and notebook

• Data Enrichment and notebook

Steps (Use)

Install Watchful Python SDK from PyPI (Recommended)

If you want to use Python to communicate with the Watchful API, you'll need to install the Watchful Python SDK from PyPI.

• Install your desired release version (they can be found at PyPI)

pip3 install watchful[==your.desired.version]

Install Optional Dependencies for Enrichment

If you intend to enrich using either SpaCy or Flair, you can take advantage of the enrichers we ship with the library. To do so, specify enrich when installing the library.

pip3 install watchful[enrich]

Basic Usage

Once you have installed the SDK, import it and begin interacting with it.

For a more thorough Watchful API introduction, read through our API Introduction Jupyter Notebook.

Basic Enrichment

The Watchful SDK aims to make enrichment a straight-forward task. The following steps assume a brand new user without any projects.

• Ensure you have the proper Python version and environment setup. Follow the environment setup guide for more details.
• Open the Watchful App
• Create a new Project
• Import a dataset into your Project
• Install the latest Watchful SDK from PyPI
  • python3 -m pip install watchful
• Install spaCy
  • python3 -m pip install spacy
• Install spaCy's en_core_web_sm model
  • python -m spacy download en_core_web_sm
• Enrich your currently opened Watchful project’s dataset via terminal window:
  • python3 -m watchful.enrich --host localhost --port 9001    # Enter your actual host and port.

Note: Enrich via Jupyter Notebook - A more comprehensive guide to enrichment is available in the Enrichment Introduction Jupyter Notebook.

For more guides and documentation, see the ReadMe in the examples directory.

Code Practices

If contributing to this code, you're encouraged to apply the following code practices.

• Apply linting and formatting

cd to/the/repo_directory/that/being/watchful-py

pylama src/watchful/ -o pylama.ini

black src/watchful/ --config=pyproject.toml --diff

Build & Install Watchful Package Locally

• Build the package

hatch build

• Install the built package (add --force-reinstall to guarantee a full (re)installation)

pip3 install dist/watchful-<latest.release.version>-py3-none-any.whl [--force-reinstall]

<latest.release.version> can be found here.

• Show the installed watchful package

pip3 show watchful

Use Watchful Package in Development Mode (Optional)

• Interactively use or test package while in development mode

pip3 install -e . [--force-reinstall]

Install Watchful Package from PyPI (Optional)

• Install your desired release version (they can be found at PyPI)

pip3 install watchful[==your.desired.version]

Run Tests

After you've done the preceding steps correctly, you will be able to see the following.

• Print Watchful version

python3 -c 'import watchful; print(watchful.__version__);'

• Run tests

pytest -W ignore::DeprecationWarning tests/test_*.py -v

Steps (Release)

After you've done the preceding steps correctly, you will be able to publish Watchful Package to PyPI. Before cutting a release, ensure the release changes are communicated with [e-mail]. There may be corresponding changes required in the Watchful application; do not worry about this as it will be taken care of by Watchful.

Prepare Release

1. Ensure your main branch is updated and create a new branch:

git checkout main && git pull && git checkout -b bump-version

1. Bump the version in the version file:

• e.g. from 1.0.0 to 1.0.1

1. Commit and push the branch to Github:

git add src/watchful/VERSION && git commit -m 'bump version' && git push -u origin bump-version

1. Open a pull request in Github and merge it to main after it is approved.

Create Release

1. Visit Watchful Python Package Releases in Github
2. Click Draft a new release
3. Click Choose a tag
   • Type in va.b.c where a.b.c is the version in the version file (e.g. v1.0.1 if the version in the version file is 1.0.1)
   • Type in the release title, which is the same value as above, i.e. va.b.c
4. Ensure Target is set to main (should be default)
5. Ensure Previous tag is set to the most current release tag (should be default)
6. Click Generate release notes
7. Click Publish release

The release will be triggered and CI will automatically build and publish the Watchful Python Package to PyPI.