Welcome to poetry-poems’s documentation!
Poems
Poetry Environment Switcher
Overview
Poetry-poems is a tool that speeds up switching between Python Poetry-based projects by:
navigating to a specific project in the terminal
activating Poetry shell at the same time.
Poetry-poems was inspired and is based on amazing project pipenv-pipes - Pipenv Environment Switcher.
How does it work?
The list of available projects has to be populated before usage!
Populating poems list
Documentation
Documentation is available on poetry-poems.readthedocs.io
License
Credits
Project based on Pipes, Pipenv Environment Switcher. A modified version of Pick for curses based interactive selection list in the terminal is also used.
Installation
Compatibility
Python 3.6+ (for Python 3.6 it may be necessary to run
export LC_ALL=en_US.utf-8)Ubuntu
MacOS
Windows10
Working in Command Prompt, PowerShell, Git Bash, Cmder
For Git Bash invoking the tool may require prefixing the commands with
winpty. More reading: git-for-windows, winpty.$ winpty poems
Stable Release
To install most recent Poetry Poems version, run the following command in your terminal (MacOS + Ubuntu + Windows):
$ pip3 install poetry-poems
Note
Poems requires the curses module, which is a part of the Python standard library and ready to use on Unix systems. However, curses module is not available on Windows. Therefore, Poems automatically installs windows-curses for Windows.
Usage
Terminology
poem
Python project developed with Poetry
Poems Registry
.poetry-poemsfile that stores paths to all poems available to poetry-poems. It is created in your$HOMEdirectory.
Interactive Switcher
Choose your poem from a prepopulated list with an interactive switcher. Adding poems to the Poem Registry is required, see: Add a new poem.
$ poems
Choosing a poem will cd into the project directory and activate the corresponding Poetry Shell.
Add a new poem
Before using Poems to activate a poem, its path has to be added to the Poems Registry:
$ poems --add <project_path>
$ poems --add $PWD
$ poems --add .
Note
Virtual environments created with Poetry (poetry shell) by default are kept in poetry config virtualenvs.path. They do not store paths to projects (as you may use the same virtual environment in multiple projects). However, it is possible to get a link from the project to the corresponding Poetry virtual environment. Therefore, Poems takes advantage of a hidden file .poetry-poems that is created to store paths to Poetry projects.
.venv in project
In case you would like to activate a poem with a virtual environment located in the project directory (created by Poetry or with virtualenv), please make sure that Poetry is configured correctly in the project directory:
$ cd <project_path>
$ poetry config --local virtualenvs.in-project true
Currently, virtual environments called .venv are supported.
Note
This command is helpful to see the virtual environment associated with Poetry project:
$ poetry env list --full-path
Keyboard Shortcuts
The Interactive environment switcher accepts the following commands:
UP+DOWN: Scroll through the listENTER: Select and activate the poemESC: Exit PoemsLEFT+RIGHT: See the detailed information about each poemQUERY: Start writing a poem name to filter the listBACKSPACE: Delete last character from filter termDEL: Clear filter
Activate a poem from the Command Line
Activate a project directly by writing poems followed by a poem name:
$ poems project1
If a query term (eg. proj) matches more than one project,
the Interactive Switcher will launch with the list filtered by
the entered query term.
Other commands
List Environments
This command will list all poems saved in Poems Registry:
$ poems --list
Output:
BBreaker *
MemoryMuppets *
venv_by_virtualenv *
venv_by_poetry *
not_poetry_project *
not_existent_project *
See more details about each poem:
$ poems --list --verbose
Output:
POETRY_HOME: /.cache/pypoetry/virtualenvs
BBreaker *
Environment: ~.cache~pypoetry~virtualenvs~bbreaker-z2QUBx6S-py3.9
Binary: Python 3.9.1
Project Dir: ~apps~BBreaker
MemoryMuppets *
Environment: ~.cache~pypoetry~virtualenvs~memorymuppets-HTGmVbtZ-py3.8
Binary: Python 3.8.7
Project Dir: ~apps~MemoryMuppets
venv_by_virtualenv *
Environment: ~apps~venv_by_virtualenv~.venv
Binary: Python 3.8.7
Project Dir: ~apps~venv_by_virtualenv
venv_by_poetry *
Environment: ~apps~venv_by_poetry~.venv
Binary: Python 3.7.9
Project Dir: ~apps~venv_by_poetry
not_poetry_project *
Environment: -- Not configured --
Binary: -- Not configured --
Project Dir: ~apps~not_poetry_project
not_existent_project *
Environment: -- Not configured --
Binary: -- Not configured --
Project Dir: ~apps~not_existent_project
Delete poem
This deletes only a path to the poem from the Poems Registry. The project and virtual environment remain untouched.
$ poems --delete not_poetry_project
Output:
Are you sure you want to delete: '/apps/not_poetry_project' from poems file? [y/N]: y
Poem 'not_poetry_project' deleted from poems file
Custom Poems Registry
It is possible to use custom Poems Registry file (in case you work on microservices belonging to one particular project):
$ poems --poems_file <custom_poems_file>
Usage Help
The list of available commands together with short descriptions can be accessed right in the command line:
$ poems --help
Shell Completion
Autocomplete option is available because of a special --_completion flag, provided by the poems cli.
Below are instructions for setting up autocompletion for Bash, Zsh, Fish, and pdksh.
Note
After setting the completions, please, remember to restart your session or open a new terminal ;)
Warning
Autocompletin does not work when a virtualenv shell is already active.Make sure that you are not inside one before usage!
Bash + zsh
Add the code below to your .bashrc/.zshrc:
export BASE_SHELL=$(basename $SHELL)
if [[ "$BASE_SHELL" == "zsh" ]] ; then
autoload bashcompinit && bashcompinit
fi
_poetry_poems_completions() {
COMPREPLY=($(compgen -W "$(poems --_completion)" -- "${COMP_WORDS[1]}"))
}
complete -F _poetry_poems_completions poems
Fish
Add a new file poems.fish to your Fish config folder (eg. ~/.config/fish/completions/poems.fish):
complete --command poems --arguments '(poems --_completion (commandline -cp))' --no-files
pdksh
To have a shell completion, write into your personal ~/.profile, after the call of exported environments variables for your Python, as WORKON_HOME:
set -A complete_poems -- $(poems --_completion)
Credits
Contributing & Development
Contributions are welcome and greatly appreciated!
How to Contribute
Report Bugs
Report bugs at https://github.com/harper25/poetry-poems/issues
Fix Bugs
Scan through the issues on GitHub. Please, feel free to implement a fix to any issue tagged with “bug” and “help wanted”.
Implement Features
Scan through the issues on GitHub. Please, feel free to implement any feature tagged with “enhancement” and “help wanted”.
Write Documentation
Please, update the documentation after the bugfixes, new feature implementations and in any case when it is unclear, not detailed enough or outdated.
Submit Feedback
The best way to send feedback is to:
Create a new issue at https://github.com/harper25/poetry-poems/issues
Star the project :)
When you are proposing a new feature:
Explain carefully your idea
Keep the scope as narrow as possible, to make it easier to implement
Consider involving youself in providing a solution :)
Setup Development Environment
Ready to contribute? Here’s how to set up Poems for local development.
Fork poetry-poems project on GitHub.
Clone your fork locally:
$ git clone git@github.com:YOUR_GITHUB_USERNAME/poetry-poems.gitCreate a virtual environment with Poetry:
$ cd poetry_poems $ poetry install $ poetry shell
Create a branch for local development so you can make your changes locally:
$ git checkout -b issue-<issue-no>/<name-of-your-bugfix-or-feature>Make sure that the code passes all tests after implementing changes. See the Testing section below for more details.
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Short and meaningful commit message" -m "Detailed description of your changes." $ git push origin issue-<issue-no>/<name-of-your-bugfix-or-feature>
Submit a pull request through the GitHub website.
Testing
Run unit tests
Unit tests are written in pytest.
$ pytest
Tox
It is possible to run the tests on all configured Python versions locally (it is also done in the CI pipeline). However, when using pyenv it is necessary to make them available to tox. It is possible by running:
$ pyenv local 3.6.9 3.7.5 3.8.3 3.9.0
$ tox
Note
Python versions have to be installed with Pyenv first:
$ pyenv versions
$ pyenv install --list
$ pyenv install 3.6.9
Linter
The code is formatted with isort and black. Flake8 is used as a static linter.
$ isort .
$ black .
$ flake8 .
Pull Request Guidelines
Before submitting your pull request, please check if it meets these guidelines:
The pull request should contain tests that cover the new code (or decent amount).
The new functionalities should be described in the updated documentation.
The pull request should work for Python 3.6+. Please, check if the CI pipeline is passing: https://travis-ci.org/github/harper25/poetry-poems/pull_requests.
Deployment
Reminder on how to release a new version:
Bump a version in the project
Push a tag to GitHub
Release manually to PyPI
History
0.2.2 (2022-10-08)
Fix Dockerfiles for testing poetry-poems (#12)
Fix slow CLI responsiveness when checking details (partially #3)
Fix error message when activating non-existent project (#4)
Update project dependencies
0.2.1 (2021-06-06)
Fix poems for Windows - crashing on subproccess calls
Fix displaying poems details for Windows in colored terminals
0.2.0 (2021-02-11)
First release on PyPi
ReadTheDocs Documentation
Show hint when adding a project with virtual environment inside project directory
0.1.0 (2021-01-24)
First release on GitHub