Skip to content

Commit d80ba20

Browse files
planniganplannigan
authored
Merge pull request #34 from wayfair-incubator/clean_up_package_description
Provide a better intro to the project in the README/long package description
2 parents ddfd827 + f412786 commit d80ba20

5 files changed

Lines changed: 198 additions & 101 deletions

File tree

‎README.md‎

Lines changed: 70 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,103 @@
11
[![CI pipeline status](https://github.com/wayfair-incubator/columbo/workflows/CI/badge.svg?branch=main)][ci]
2+
[![PyPI](https://img.shields.io/pypi/v/columbo)][pypi]
3+
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/columbo)][pypi]
24
[![codecov](https://codecov.io/gh/wayfair-incubator/columbo/branch/main/graph/badge.svg)][codecov]
3-
TODO: PyPi Release Badge
45
[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)][mypy-home]
56
[![Code style: black](https://img.shields.io/badge/code%20style-black-black.svg)][black-home]
67

78
# Columbo
89

910
Specify a dynamic set of questions to ask a user and get their answers.
1011

11-
## CI
12+
`columbo`'s feature set allows a program to:
1213

13-
TODO: Add CI documentation.
14+
* Ask multiple types of questions:
15+
* Yes or No
16+
* Multiple choice
17+
* Open-ended
18+
* Validate the response provided by the user.
19+
* Use answers from earlier questions:
20+
* As part of the text of a question
21+
* As part of the text of a default value
22+
* To decide if a question should be skipped
23+
* Accept answers from the command line in addition to prompting the user.
1424

15-
## Usage
25+
## Example
1626

17-
TODO: Add usage documentation.
27+
### User Prompts
1828

19-
## Develop
20-
21-
The Columbo project uses Docker to ease setting up a consistent development environment. The Docker documentation has
22-
details on how to [install docker][install-docker] on your computer.
23-
24-
Once that is configured, the test suite can be run locally:
25-
26-
```bash
27-
docker-compose run --rm test
28-
```
29-
30-
If you want to be able to execute code in the container:
31-
32-
```bash
33-
docker-compose run --rm devbox
34-
(your code here)
35-
```
36-
37-
In the devbox environment you'll be able to enter a python shell and import `columbo` or any dependencies.
38-
39-
## Debugging
40-
41-
The docker container has [pdb++][pdbpp-home] install that can be used as a debugger. (However, you are welcome to set up
42-
a different debugger if you would like.)
43-
44-
This allows you to easily create a breakpoint anywhere in the code.
29+
The primary use of `columbo` is to define a sequence of interactions that are used to prompt a user to provide answers
30+
using a terminal. Below is a sample which shows some ways this can be used.
4531

4632
```python
47-
def my_function():
48-
breakpoint()
49-
...
33+
import columbo
34+
35+
interactions = [
36+
columbo.Echo("Welcome to the Columbo example"),
37+
columbo.Acknowledge(
38+
"Press enter to start"
39+
),
40+
columbo.BasicQuestion(
41+
"user",
42+
"What is your name?",
43+
default="Patrick",
44+
),
45+
columbo.BasicQuestion(
46+
"user_email",
47+
lambda answers: f"""What email address should be used to contact {answers["user"]}?""",
48+
default="me@example.com"
49+
),
50+
columbo.Choice(
51+
"mood",
52+
"How are you feeling today?",
53+
options=["happy", "sad", "sleepy", "confused"],
54+
default="happy",
55+
),
56+
columbo.Confirm("likes_dogs", "Do you like dogs?", default=True),
57+
]
58+
59+
answers = columbo.get_answers(interactions)
60+
print(answers)
5061
```
5162

52-
When your the code, you will drop into an interactive `pdb++` debugger.
63+
Below shows the output when the user accepts the default values for most of the questions. The user provides a different
64+
value for the email and explicitly confirms that they like dogs.
5365

54-
See the documentation on [pdb][pdb-docs] and [pdb++][pdbpp-docs] for more information.
66+
```text
67+
Welcome to the Columbo example
68+
Press enter to start
69+
70+
What is your name? [Patrick]:
5571
56-
## Testing
57-
58-
You'll be unable to merge code unless the linting and tests pass. You can run these in your container via:
59-
60-
```bash
61-
docker-compose run --rm test
62-
```
72+
What email address should be used to contact Patrick? [me@example.com]: patrick@example.com
6373
64-
This will run the same tests, linting, and code coverage that are run by the CI pipeline. The only difference is that,
65-
when run locally, `black` and `isort` are configured to automatically correct issues they detect.
74+
How are you feeling today?
75+
1 - happy
76+
2 - sad
77+
3 - sleepy
78+
4 - confused
79+
Enter the number of your choice [1]:
6680
67-
Generally we should endeavor to write tests for every feature. Every new feature branch should increase the test
68-
coverage rather than decreasing it.
81+
Do you like dogs? (Y/n): y
6982
70-
We use [pytest][pytest-docs] as our testing framework.
71-
72-
#### Stages
73-
74-
To customize / override a specific testing stage, please read the documentation specific to that tool:
75-
76-
1. [PyTest][pytest-docs]
77-
2. [MyPy][mypy-docs]
78-
3. [Black][black-docs]
79-
4. [Isort][isort-docs]
80-
4. [Flake8][flake8-docs]
81-
5. [Bandit][bandit-docs]
82-
83-
### `setup.py`
84-
85-
Setuptools is used to packaging the library.
86-
87-
**`setup.py` must not import anything from the package** When installing from source, the user may not have the
88-
packages dependencies installed, and importing the package is likely to raise an `ImportError`. For this reason, the
89-
**package version should be obtained without importing**. This is explains why `setup.py` uses a regular expression to
90-
grabs the version from `__init__.py` without actually importing.
91-
92-
### Requirements
93-
94-
* **requirements.txt** - Lists all direct dependencies (packages imported by the library).
95-
* **Requirements-test.txt** - Lists all direct requirements needed to run the test suite & lints.
96-
97-
## Publishing the Package
98-
99-
TODO: Not currently implemented.
100-
101-
Once the package is ready to be released, there are a few things that need to be done:
83+
{'user': 'Patrick', 'user_email': 'patrick@example.com', 'mood': 'happy', 'likes_dogs': True}
84+
```
10285

103-
1. Create a new Pull Request that increase the version number from the previous release in `columbo/__init__.py` and
104-
`CHANGELOG.md`. [Semantic versioning][sem-ver] is used to make it clear to people using your package what types of
105-
changes are in the new version.
106-
2. Ensure this change has been merged to the default branch with all the code that should be included in the release.
107-
3. Create a new GitHub release. The tag should be named: `vX.Y.Z`
86+
### Command Line Answers
10887

109-
This will trigger the CI system to build a wheel and a source distributions of the package and push them to
110-
[PyPI][pypi].
88+
TODO
11189

11290
## Documentation
11391

114-
TODO: Use Github Pages to host documentation.
115-
Check out the [project documentation][columbo-docs]
92+
Check out the [project documentation][columbo-docs].
93+
94+
For an overview on how repository structure and how to work with the code base, read the
95+
[Development Guide][development-docs].
11696

11797
[ci]: https://github.com/wayfair-incubator/columbo/actions
98+
[pypi]: https://pypi.org/project/columbo/
11899
[codecov]: https://codecov.io/gh/wayfair-incubator/columbo
119100
[mypy-home]: http://mypy-lang.org/
120101
[black-home]: https://github.com/psf/black
121-
[install-docker]: https://docs.docker.com/install/
122-
[pdbpp-home]: https://github.com/pdbpp/pdbpp
123-
[pdb-docs]: https://docs.python.org/3/library/pdb.html
124-
[pdbpp-docs]: https://github.com/pdbpp/pdbpp#usage
125-
[pytest-docs]: https://docs.pytest.org/en/latest/
126-
[mypy-docs]: https://mypy.readthedocs.io/en/stable/
127-
[black-docs]: https://black.readthedocs.io/en/stable/
128-
[isort-docs]: https://pycqa.github.io/isort/
129-
[flake8-docs]: http://flake8.pycqa.org/en/stable/
130-
[bandit-docs]: https://bandit.readthedocs.io/en/stable/
131-
[sem-ver]: https://semver.org/
132-
[pypi]: https://semver.org/
133102
[columbo-docs]: https://github.com/wayfair-incubator/columbo/
103+
[development-docs]: https://github.com/wayfair-incubator/columbo/development-guide/

‎docs/development-guide.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Development Guide
2+
3+
Welcome! Thank you for wanting to make the project better. This section provides an overview on how repository structure
4+
and how to work with the code base.
5+
6+
Before you dive into this, it is best to read:
7+
8+
* The whole [Usage Guide][usage-guide]
9+
* The [Code of Conduct][code of conduct]
10+
* The [Contributing][contributing] guide
11+
12+
## Docker
13+
14+
The Columbo project uses Docker to ease setting up a consistent development environment. The Docker documentation has
15+
details on how to [install docker][install-docker] on your computer.
16+
17+
Once that is configured, the test suite can be run locally:
18+
19+
```bash
20+
docker-compose run --rm test
21+
```
22+
23+
If you want to be able to execute code in the container:
24+
25+
```bash
26+
docker-compose run --rm devbox
27+
(your code here)
28+
```
29+
30+
In the devbox environment you'll be able to enter a python shell and import `columbo` or any dependencies.
31+
32+
## Debugging
33+
34+
The docker container has [pdb++][pdbpp-home] install that can be used as a debugger. (However, you are welcome to set up
35+
a different debugger if you would like.)
36+
37+
This allows you to easily create a breakpoint anywhere in the code.
38+
39+
```python
40+
def my_function():
41+
breakpoint()
42+
...
43+
```
44+
45+
When your the code, you will drop into an interactive `pdb++` debugger.
46+
47+
See the documentation on [pdb][pdb-docs] and [pdb++][pdbpp-docs] for more information.
48+
49+
## Testing
50+
51+
You'll be unable to merge code unless the linting and tests pass. You can run these in your container via:
52+
53+
```bash
54+
docker-compose run --rm test
55+
```
56+
57+
This will run the same tests, linting, and code coverage that are run by the CI pipeline. The only difference is that,
58+
when run locally, `black` and `isort` are configured to automatically correct issues they detect.
59+
60+
Generally we should endeavor to write tests for every feature. Every new feature branch should increase the test
61+
coverage rather than decreasing it.
62+
63+
We use [pytest][pytest-docs] as our testing framework.
64+
65+
#### Stages
66+
67+
To customize / override a specific testing stage, please read the documentation specific to that tool:
68+
69+
1. [PyTest][pytest-docs]
70+
2. [MyPy][mypy-docs]
71+
3. [Black][black-docs]
72+
4. [Isort][isort-docs]
73+
4. [Flake8][flake8-docs]
74+
5. [Bandit][bandit-docs]
75+
76+
### `setup.py`
77+
78+
Setuptools is used to packaging the library.
79+
80+
**`setup.py` must not import anything from the package** When installing from source, the user may not have the
81+
packages dependencies installed, and importing the package is likely to raise an `ImportError`. For this reason, the
82+
**package version should be obtained without importing**. This is explains why `setup.py` uses a regular expression to
83+
grabs the version from `__init__.py` without actually importing.
84+
85+
### Requirements
86+
87+
* **requirements.txt** - Lists all direct dependencies (packages imported by the library).
88+
* **Requirements-test.txt** - Lists all direct requirements needed to run the test suite & lints.
89+
90+
## Publishing the Package
91+
92+
TODO: Not currently implemented.
93+
94+
Once the package is ready to be released, there are a few things that need to be done:
95+
96+
1. Create a new Pull Request that increase the version number from the previous release in `columbo/__init__.py` and
97+
`CHANGELOG.md`. [Semantic versioning][sem-ver] is used to make it clear to people using your package what types of
98+
changes are in the new version.
99+
2. Ensure this change has been merged to the default branch with all the code that should be included in the release.
100+
3. Create a new GitHub release. The tag should be named: `vX.Y.Z`
101+
102+
This will trigger the CI system to build a wheel and a source distributions of the package and push them to
103+
[PyPI][pypi].
104+
105+
## Continuous Integration Pipeline
106+
107+
TODO: Add CI documentation.
108+
109+
[usage-guide]: usage-guide/fundamentals.md
110+
[code of conduct]: https://github.com/wayfair-incubator/columbo/blob/main/CODE_OF_CONDUCT.md
111+
[contributing]: https://github.com/wayfair-incubator/columbo/blob/main/CONTRIBUTING.md
112+
[install-docker]: https://docs.docker.com/install/
113+
[pdbpp-home]: https://github.com/pdbpp/pdbpp
114+
[pdb-docs]: https://docs.python.org/3/library/pdb.html
115+
[pdbpp-docs]: https://github.com/pdbpp/pdbpp#usage
116+
[pytest-docs]: https://docs.pytest.org/en/latest/
117+
[mypy-docs]: https://mypy.readthedocs.io/en/stable/
118+
[black-docs]: https://black.readthedocs.io/en/stable/
119+
[isort-docs]: https://pycqa.github.io/isort/
120+
[flake8-docs]: http://flake8.pycqa.org/en/stable/
121+
[bandit-docs]: https://bandit.readthedocs.io/en/stable/
122+
[sem-ver]: https://semver.org/
123+
[pypi]: https://pypi.org/project/columbo/

‎docs/index.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
# Columbo
22

33
[![CI pipeline status](https://github.com/wayfair-incubator/columbo/workflows/CI/badge.svg?branch=main)][ci]
4+
[![PyPI](https://img.shields.io/pypi/v/columbo)][pypi]
5+
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/columbo)][pypi]
46
[![codecov](https://codecov.io/gh/wayfair-incubator/columbo/branch/main/graph/badge.svg)][codecov]
5-
TODO: PyPi Release Badge
67

78
`columbo` provides a way to specify a dynamic set of questions to ask a user and get their answers.
89

@@ -97,6 +98,7 @@ To learn more about the various ways `columbo` can be used, read the [Usage Guid
9798
To find detailed information about a specific function or class, read the [API Reference][api-reference].
9899

99100
[ci]: https://github.com/wayfair-incubator/columbo/actions
101+
[pypi]: https://pypi.org/project/columbo/
100102
[codecov]: https://codecov.io/gh/wayfair-incubator/columbo
101103
[getting-started]: getting-started.md
102104
[usage-guide]: usage-guide/fundamentals.md

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ nav:
1313
- Validators: usage-guide/validators.md
1414
- Command Line Interface: usage-guide/command-line.md
1515
- Reference: api.md
16+
- Development Guide: development-guide.md
1617
- Changelog: CHANGELOG.md
1718
theme: material
1819
markdown_extensions:

‎setup.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
author_email="plannigan@wayfair.com",
2222
description="Specify a dynamic set of questions to ask a user and get their answers.",
2323
long_description=open("README.md").read(),
24+
long_description_content_type="text/markdown",
2425
packages=setuptools.find_packages(
2526
exclude=["*.tests", "*.tests.*", "tests.*", "tests"]
2627
),

0 commit comments

Comments
 (0)