Skip to content

Commit

Permalink
Merge pull request #34 from wayfair-incubator/clean_up_package_descri…
Browse files Browse the repository at this point in the history 
…ption

Provide a better intro to the project in the README/long package description
  • Loading branch information
@plannigan
plannigan authored Dec 18, 2020
2 parents ddfd827 + f412786 commit d80ba20
Show file tree
Hide file tree
Showing 5 changed files with 198 additions and 101 deletions.
170 changes: 70 additions & 100 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,133 +1,103 @@
[![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]

# Columbo

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="[email protected]"
),
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? [[email protected]]: [email protected]
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': '[email protected]', '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/
123 changes: 123 additions & 0 deletions docs/development-guide.md
View file
Original file line number Diff line number Diff line change
@@ -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/
4 changes: 3 additions & 1 deletion docs/index.md
View file
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
1 change: 1 addition & 0 deletions setup.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
author_email="[email protected]",
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"]
),
Expand Down

0 comments on commit d80ba20

Please sign in to comment.