diff --git a/README.md b/README.md index 146f8e15..f5d445de 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ [![CI pipeline status](https://github.com/wayfair-incubator/columbo/workflows/CI/badge.svg?branch=main)][ci] +[![PyPI](https://img.shields.io/pypi/v/columbo)][pypi] +[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/columbo)][pypi] [![codecov](https://codecov.io/gh/wayfair-incubator/columbo/branch/main/graph/badge.svg)][codecov] -TODO: PyPi Release Badge [![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)][mypy-home] [![Code style: black](https://img.shields.io/badge/code%20style-black-black.svg)][black-home] @@ -8,126 +9,95 @@ TODO: PyPi Release Badge Specify a dynamic set of questions to ask a user and get their answers. -## CI +`columbo`'s feature set allows a program to: -TODO: Add CI documentation. +* Ask multiple types of questions: + * Yes or No + * Multiple choice + * Open-ended +* Validate the response provided by the user. +* Use answers from earlier questions: + * As part of the text of a question + * As part of the text of a default value + * To decide if a question should be skipped +* Accept answers from the command line in addition to prompting the user. -## Usage +## Example -TODO: Add usage documentation. +### User Prompts -## Develop - -The Columbo project uses Docker to ease setting up a consistent development environment. The Docker documentation has -details on how to [install docker][install-docker] on your computer. - -Once that is configured, the test suite can be run locally: - -```bash -docker-compose run --rm test -``` - -If you want to be able to execute code in the container: - -```bash -docker-compose run --rm devbox -(your code here) -``` - -In the devbox environment you'll be able to enter a python shell and import `columbo` or any dependencies. - -## Debugging - -The docker container has [pdb++][pdbpp-home] install that can be used as a debugger. (However, you are welcome to set up -a different debugger if you would like.) - -This allows you to easily create a breakpoint anywhere in the code. +The primary use of `columbo` is to define a sequence of interactions that are used to prompt a user to provide answers +using a terminal. Below is a sample which shows some ways this can be used. ```python -def my_function(): - breakpoint() - ... +import columbo + +interactions = [ + columbo.Echo("Welcome to the Columbo example"), + columbo.Acknowledge( + "Press enter to start" + ), + columbo.BasicQuestion( + "user", + "What is your name?", + default="Patrick", + ), + columbo.BasicQuestion( + "user_email", + lambda answers: f"""What email address should be used to contact {answers["user"]}?""", + default="me@example.com" + ), + columbo.Choice( + "mood", + "How are you feeling today?", + options=["happy", "sad", "sleepy", "confused"], + default="happy", + ), + columbo.Confirm("likes_dogs", "Do you like dogs?", default=True), +] + +answers = columbo.get_answers(interactions) +print(answers) ``` -When your the code, you will drop into an interactive `pdb++` debugger. +Below shows the output when the user accepts the default values for most of the questions. The user provides a different +value for the email and explicitly confirms that they like dogs. -See the documentation on [pdb][pdb-docs] and [pdb++][pdbpp-docs] for more information. +```text +Welcome to the Columbo example +Press enter to start + +What is your name? [Patrick]: -## Testing - -You'll be unable to merge code unless the linting and tests pass. You can run these in your container via: - -```bash -docker-compose run --rm test -``` +What email address should be used to contact Patrick? [me@example.com]: patrick@example.com -This will run the same tests, linting, and code coverage that are run by the CI pipeline. The only difference is that, -when run locally, `black` and `isort` are configured to automatically correct issues they detect. +How are you feeling today? +1 - happy +2 - sad +3 - sleepy +4 - confused +Enter the number of your choice [1]: -Generally we should endeavor to write tests for every feature. Every new feature branch should increase the test -coverage rather than decreasing it. +Do you like dogs? (Y/n): y -We use [pytest][pytest-docs] as our testing framework. - -#### Stages - -To customize / override a specific testing stage, please read the documentation specific to that tool: - -1. [PyTest][pytest-docs] -2. [MyPy][mypy-docs] -3. [Black][black-docs] -4. [Isort][isort-docs] -4. [Flake8][flake8-docs] -5. [Bandit][bandit-docs] - -### `setup.py` - -Setuptools is used to packaging the library. - -**`setup.py` must not import anything from the package** When installing from source, the user may not have the -packages dependencies installed, and importing the package is likely to raise an `ImportError`. For this reason, the -**package version should be obtained without importing**. This is explains why `setup.py` uses a regular expression to -grabs the version from `__init__.py` without actually importing. - -### Requirements - -* **requirements.txt** - Lists all direct dependencies (packages imported by the library). -* **Requirements-test.txt** - Lists all direct requirements needed to run the test suite & lints. - -## Publishing the Package - -TODO: Not currently implemented. - -Once the package is ready to be released, there are a few things that need to be done: +{'user': 'Patrick', 'user_email': 'patrick@example.com', 'mood': 'happy', 'likes_dogs': True} +``` -1. Create a new Pull Request that increase the version number from the previous release in `columbo/__init__.py` and - `CHANGELOG.md`. [Semantic versioning][sem-ver] is used to make it clear to people using your package what types of - changes are in the new version. -2. Ensure this change has been merged to the default branch with all the code that should be included in the release. -3. Create a new GitHub release. The tag should be named: `vX.Y.Z` +### Command Line Answers -This will trigger the CI system to build a wheel and a source distributions of the package and push them to -[PyPI][pypi]. +TODO ## Documentation -TODO: Use Github Pages to host documentation. -Check out the [project documentation][columbo-docs] +Check out the [project documentation][columbo-docs]. + +For an overview on how repository structure and how to work with the code base, read the +[Development Guide][development-docs]. [ci]: https://github.com/wayfair-incubator/columbo/actions +[pypi]: https://pypi.org/project/columbo/ [codecov]: https://codecov.io/gh/wayfair-incubator/columbo [mypy-home]: http://mypy-lang.org/ [black-home]: https://github.com/psf/black -[install-docker]: https://docs.docker.com/install/ -[pdbpp-home]: https://github.com/pdbpp/pdbpp -[pdb-docs]: https://docs.python.org/3/library/pdb.html -[pdbpp-docs]: https://github.com/pdbpp/pdbpp#usage -[pytest-docs]: https://docs.pytest.org/en/latest/ -[mypy-docs]: https://mypy.readthedocs.io/en/stable/ -[black-docs]: https://black.readthedocs.io/en/stable/ -[isort-docs]: https://pycqa.github.io/isort/ -[flake8-docs]: http://flake8.pycqa.org/en/stable/ -[bandit-docs]: https://bandit.readthedocs.io/en/stable/ -[sem-ver]: https://semver.org/ -[pypi]: https://semver.org/ [columbo-docs]: https://github.com/wayfair-incubator/columbo/ +[development-docs]: https://github.com/wayfair-incubator/columbo/development-guide/ diff --git a/docs/development-guide.md b/docs/development-guide.md new file mode 100644 index 00000000..a5d90bad --- /dev/null +++ b/docs/development-guide.md @@ -0,0 +1,123 @@ +# Development Guide + +Welcome! Thank you for wanting to make the project better. This section provides an overview on how repository structure +and how to work with the code base. + +Before you dive into this, it is best to read: + +* The whole [Usage Guide][usage-guide] +* The [Code of Conduct][code of conduct] +* The [Contributing][contributing] guide + +## Docker + +The Columbo project uses Docker to ease setting up a consistent development environment. The Docker documentation has +details on how to [install docker][install-docker] on your computer. + +Once that is configured, the test suite can be run locally: + +```bash +docker-compose run --rm test +``` + +If you want to be able to execute code in the container: + +```bash +docker-compose run --rm devbox +(your code here) +``` + +In the devbox environment you'll be able to enter a python shell and import `columbo` or any dependencies. + +## Debugging + +The docker container has [pdb++][pdbpp-home] install that can be used as a debugger. (However, you are welcome to set up +a different debugger if you would like.) + +This allows you to easily create a breakpoint anywhere in the code. + +```python +def my_function(): + breakpoint() + ... +``` + +When your the code, you will drop into an interactive `pdb++` debugger. + +See the documentation on [pdb][pdb-docs] and [pdb++][pdbpp-docs] for more information. + +## Testing + +You'll be unable to merge code unless the linting and tests pass. You can run these in your container via: + +```bash +docker-compose run --rm test +``` + +This will run the same tests, linting, and code coverage that are run by the CI pipeline. The only difference is that, +when run locally, `black` and `isort` are configured to automatically correct issues they detect. + +Generally we should endeavor to write tests for every feature. Every new feature branch should increase the test +coverage rather than decreasing it. + +We use [pytest][pytest-docs] as our testing framework. + +#### Stages + +To customize / override a specific testing stage, please read the documentation specific to that tool: + +1. [PyTest][pytest-docs] +2. [MyPy][mypy-docs] +3. [Black][black-docs] +4. [Isort][isort-docs] +4. [Flake8][flake8-docs] +5. [Bandit][bandit-docs] + +### `setup.py` + +Setuptools is used to packaging the library. + +**`setup.py` must not import anything from the package** When installing from source, the user may not have the +packages dependencies installed, and importing the package is likely to raise an `ImportError`. For this reason, the +**package version should be obtained without importing**. This is explains why `setup.py` uses a regular expression to +grabs the version from `__init__.py` without actually importing. + +### Requirements + +* **requirements.txt** - Lists all direct dependencies (packages imported by the library). +* **Requirements-test.txt** - Lists all direct requirements needed to run the test suite & lints. + +## Publishing the Package + +TODO: Not currently implemented. + +Once the package is ready to be released, there are a few things that need to be done: + +1. Create a new Pull Request that increase the version number from the previous release in `columbo/__init__.py` and + `CHANGELOG.md`. [Semantic versioning][sem-ver] is used to make it clear to people using your package what types of + changes are in the new version. +2. Ensure this change has been merged to the default branch with all the code that should be included in the release. +3. Create a new GitHub release. The tag should be named: `vX.Y.Z` + +This will trigger the CI system to build a wheel and a source distributions of the package and push them to +[PyPI][pypi]. + +## Continuous Integration Pipeline + +TODO: Add CI documentation. + +[usage-guide]: usage-guide/fundamentals.md +[code of conduct]: https://github.com/wayfair-incubator/columbo/blob/main/CODE_OF_CONDUCT.md +[contributing]: https://github.com/wayfair-incubator/columbo/blob/main/CONTRIBUTING.md +[install-docker]: https://docs.docker.com/install/ +[pdbpp-home]: https://github.com/pdbpp/pdbpp +[pdb-docs]: https://docs.python.org/3/library/pdb.html +[pdbpp-docs]: https://github.com/pdbpp/pdbpp#usage +[pytest-docs]: https://docs.pytest.org/en/latest/ +[mypy-docs]: https://mypy.readthedocs.io/en/stable/ +[black-docs]: https://black.readthedocs.io/en/stable/ +[isort-docs]: https://pycqa.github.io/isort/ +[flake8-docs]: http://flake8.pycqa.org/en/stable/ +[bandit-docs]: https://bandit.readthedocs.io/en/stable/ +[sem-ver]: https://semver.org/ +[pypi]: https://pypi.org/project/columbo/ diff --git a/docs/index.md b/docs/index.md index db7a7eb2..6d5071ab 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,9 @@ # Columbo [![CI pipeline status](https://github.com/wayfair-incubator/columbo/workflows/CI/badge.svg?branch=main)][ci] +[![PyPI](https://img.shields.io/pypi/v/columbo)][pypi] +[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/columbo)][pypi] [![codecov](https://codecov.io/gh/wayfair-incubator/columbo/branch/main/graph/badge.svg)][codecov] -TODO: PyPi Release Badge `columbo` provides a way to specify a dynamic set of questions to ask a user and get their answers. @@ -97,6 +98,7 @@ To learn more about the various ways `columbo` can be used, read the [Usage Guid To find detailed information about a specific function or class, read the [API Reference][api-reference]. [ci]: https://github.com/wayfair-incubator/columbo/actions +[pypi]: https://pypi.org/project/columbo/ [codecov]: https://codecov.io/gh/wayfair-incubator/columbo [getting-started]: getting-started.md [usage-guide]: usage-guide/fundamentals.md diff --git a/mkdocs.yml b/mkdocs.yml index faa063a3..05a8bde8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,6 +13,7 @@ nav: - Validators: usage-guide/validators.md - Command Line Interface: usage-guide/command-line.md - Reference: api.md + - Development Guide: development-guide.md - Changelog: CHANGELOG.md theme: material markdown_extensions: diff --git a/setup.py b/setup.py index 150ce269..1e640b10 100644 --- a/setup.py +++ b/setup.py @@ -21,6 +21,7 @@ author_email="plannigan@wayfair.com", description="Specify a dynamic set of questions to ask a user and get their answers.", long_description=open("README.md").read(), + long_description_content_type="text/markdown", packages=setuptools.find_packages( exclude=["*.tests", "*.tests.*", "tests.*", "tests"] ),