Package: nats-tools
NATS ToolsUseful tools to develop Python projects relying on NATSQuick startInstalling the projectUsers can install project from github usingpip:pip install nats-toolsUsing NATSDIt's possible to control NATS servers usingnats_tools.NATSD:fromnats_toolsimportNATSD# Create a new nats-server daemonnatsd=NATSD(debug=True)# Start the servernatsd.start()# Stop the servernatsd.stop()Using pytest fixturesDefine an argument namednatsdin your tests in order to get aNATSDinstance already started. The instance is stopped during test teardown.deftest_using_nats_server(natsd:NATSD):"""A test which relies on nats-server being up and running."""assertnatsd.is_alive()assertnatsd.monitor.healthz()=={"status":"ok"}Using the fixture, each test is executed using a unique nats-server running in its own process.Parametrizing fixturesIt's possible to start a NATS server with custom configuration for each test usig parametrized fixture:@parametrize_nats_server(port=5000)deftest_parametetrize_nats_server_fixture_can_be_used(natsd:NATSD):assertnatsd.port==5000Using custom fixturesIt's very easy to create a fixture similar tonatsdfixture:importpytestimporttypingastfromnats_toolsimportNATSD@pytest.fixturedefmy_natsd()->t.Iterator[NATSD]:"""Yield a started NATSD instance for each test case."""withNATSD()asnats:yieldnatsCI HelpersThe scriptinstall-nats-server.shlocated inscripts/directory can be used in CI environments to install NATS server.Developer installationThis project is packaged usingsetuptoolsand apyproject.tomlaccording toPEP 621.Starting withPEP 621, the Python community selectedpyproject.tomlas a standard way of specifying python projects metadata. Setuptools has adopted this standard and use the information contained in this file as an input in the build process.Install using scriptThe install script is responsible for first creating a virtual environment, then updating packaging dependencies such aspip,setuptoolsandwheelwithin the virtual environment. Finally, it installs the project in development mode within the virtual environment.The virtual environment is always named.venv/Run theinstall.pyscript located in thescripts/directory with the Python interpreter of your choice. The script accepts the following arguments:--dev: install extra dependencies required to contribute to development--docs: install extra dependencies required to build and serve documentation-eor--extras: a string of comma-separated extras such as"dev,docs".-aor--all: a boolean flag indicating that all extras should be installed.Example usage:Install with build extra only (default behaviour)python3 scripts/install.pyInstall with dev extrapython3 scripts/install.py --devInstall all extraspython3 scripts/install.py --allNote: Thevenvmodule must be installed for the python interpreter used to run install script. On Debian and Ubuntu systems, this package can be installed using the following command:sudo apt-get install python3-venv. On Windows systems, python distributions have thevenvmodule installed by default.Development tasksThe filetasks.pyis aninvoketask file. It describes several tasks which developers can execute to perform various actions.To list all available tasks, activate the project virtual environment, and run the commandinv --list:$inv--listAvailable tasks:build         Build sdist and wheel, and optionally build documentation.requirements  Generate requirements.txt filecheck         Run mypy typechecking.clean         Clean build artifacts and optionally documentation artifacts as well as generated bytecode.coverage      Serve code coverage results and optionally run tests before serving resultsdocker        Build cross-platform docker image for the projectdocs          Serve the documentation in development mode.format        Format source code using black and isort.lint          Lint source code using flake8.test          Run tests using pytest and optionally enable coverage.wheelhouse    Build wheelhouse for the projectBuild project artifactsThebuildtask can be used to build asource distribution (sdist), awheel binary packageby default.Optionally, it can be used to build the project documentation as a static website.Usage:Buildsdistandwheelonly:inv buildBuildsdist,wheeland documentation:inv build --docsBuilding wheelhouseThewheelhousetask can be used to generate aninstallation bundlealso known as a wheelhouse.pip wheel can be used to generate and package all of a project’s dependencies, with all the compilation performed, into a single directory that can be converted into a single archive. This archive then allows installation when index servers are unavailable and avoids time-consuming recompilation.This command does not accept any argument, and generates the wheelhouse intodist/wheelhouse.Run testsThetesttask can be used to run tests usingpytest.By default, test coverage is not enabled and-cor--covoption must be provided to enable test coverage.Usage:Run tests without coverage:inv testRun tests with coverage:inv test --covVisualize test coverageThecoveragetask can be used to serve test coverage results onhttp://localhost:8000by default. Use--portoption to use a different port.By default, test coverage is expected to be present before running the task. If it is desired to run tests before serving the results, use--runoption.Run typecheckingThechecktask can be used to runmypy.By default type checking is not run on tests and-ior--include-testsoption must be provided to include them.Run linterThelinttask can be used to lint source code usingflake8. This task does not accept any option.flake8is configured in thesetup.cfgfile.Format source codeTheformattask can be used to format source code usingblackandisort. This task does not accept any option.blackis not configured in any way, butisortis configured insetup.cfg.Serve the documentationThedocstask can be used to serve the documentation as a static website onhttp://localhost:8000with auto-reload enabled by default. Use the--portoption to change the listenning port and the--no-watchto disable auto-reload.Build Docker imageThedockertask can be used to build a Docker image for the project. The Dockerfile can be found at the root of the repository. By default, image is built forlinux/amd64only. Use--platformargument to build image for different architectures.Useinv docker --helpto learn about allowed options.Git flowTwo branches exist:next: The development branch. All developers must merge commits tonextthrough Pull Requests.main: The release branch. Developers must not commit to this branch. Only merge fromnextbranch with fast-forward strategy are allowed onmainbranch.Each time new commits are pushed onmain, semantic-release may perform a release bump according to commit messages.Git commitsDevelopers are execpted to write commit messages according to theConvetionnal Commitsspecification.Commit messages which are not valid conventionnal commits are ignored in changelog.ChangelogChangelog is generated for each release candidate and each release according to commit messages found since last release.Changelog content is written toCHANGELOG.mdby@semantic-release/release-notes-generatorplugin configured withconventionnalcommitpreset.Contributing to the documentationProject documentation is written usingMkDocsstatic site generator. Documentation source files are written inMarkdown. They can be found indocs/directory.Aside from documentation written in markdown files, Python API reference is generated from docstrings and type annotations found in source code.AcknowledgementsMost of the code used in this project directly comes from or is inspired bynats-pytesting module.nats-pyis licensed underApache-2.0