Starting New Python Projects on a MacBook

readme.md

Starting New Python Projects on a MacBook

Made with ♥ by Polyglot.

This guide assumes you've got a MacBook with a relatively recent OS (YMMV), homebrew (brew), and you understand how $PATH and your $SHELL works at the most basic level

Prerequisites

• Installing Python on a MacBook
• direnv

Using

In order to use this as a starting point for creating a new python project which will use external modules via standard python packaging ...

1. Follow the steps below until poetry run pytest is execting with no errors (i.e. shell exits with 0).
2. Rename the sonnet module and any references to it in the __init__.py file.
3. Rename tests/test_sonnet.py to match the new package name and modify the contents of the same file such that it no longer refers to sonnet but the new package name.

Setup new Project with updated pytest

see contents of .envrc when performing step direnv edit .

❯ poetry new sonnet
❯ mkdir -p sonneet/src/sonnet
❯ cd sonnet
❯ poetry config virtualenvs.in-project true --local
❯ echo '**/__pycache__' > .gitignore
❯ echo 'source $(poetry env info --path)/bin/activate' > .envrc
❯ direnv edit .

(optionally) Update poetry

❯ poetry self update

(optionally) Update pytest

❯ poetry update pytest

contents of src/sonnet/__init__.py

necessary so that functions defined in api module in the sonnet package so requiring modules can do from sonnet import * and the sonnet package has a version

from sonnet.api import stats

__version__ = '0.0.1'

contents of tests/test_sonnet.py file

We've added test coverage for the version and the api function stats

❯ cat tests/test_sonnet.py
from sonnet import __version__, stats

def test_version():
    assert __version__ == '0.0.1'

def test_stats_name():
    assert stats.__name__ == 'stats'

def test_stats_char_count():
    assert stats()['char_count'] == 10000
    assert stats()['word_count'] == 553
    assert stats()['byte_count'] == 1024

contents of src/sonnet/api.py

We've implemented the stats function such that it's return value satisfies the tests

❯ cat src/sonnet/api.py
def stats():
    return dict([
        ('char_count', 10000),
        ('word_count', 553),
        ('byte_count', 1024)
    ])

Execute Test Suite

.venv ❯ poetry run pytest
=============================================== test session starts ===============================================
platform darwin -- Python 3.8.0, pytest-5.4.3, py-1.9.0, pluggy-0.13.1
rootdir: /Users/wilmoore/Documents/projects/@exl/sonnet
collected 3 items

tests/test_sonnet.py ...                                                                                    [100%]

================================================ 3 passed in 0.02s ================================================

Useful Commands

Execute Test Suite

❯ poetry install
❯ poetry run pytest

Example git status

replace dotsplit with name of package/module

❯ git status
On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   .gitignore
        new file:   poetry.lock
        new file:   pyproject.toml
        new file:   readme.md
        new file:   src/dotsplit/__init__.py
        new file:   tests/__init__.py
        new file:   tests/test_dotsplit.py

References

• Packages
• Testing & Packaging
• Hypermodern Python
• Absolute vs Relative Imports in Python
• Dead Simple Python: Project Structure and Imports
• What Are Python Wheels and Why Should You Care?
• The Hitchhiker's Guide to Python: Structuring Your Project
• python packaging: src layout (intermediate) anthony explains #048
• Python import: Advanced Techniques and Tips
• pytest: helps you write better programs
• The Python Standard Library
• __init__.py
• The structure
• ionelmc/cookiecutter-pylibrary
• Manage Your Python Project Using Poetry
• Python Poetry Basic Usage
• PEP 396 -- Module Version Numbers