A Shortcut To Better Python Projects – With Love From Flowtale

TL;DR: Flowtale's internal Python tool makes it easy to create well-structured projects and write consistent, high-quality code. Now you can use it too.

At Flowtale, we launch a lot of software projects every year.

We operate at a fast pace, and we have many different people working on code bases that mostly use the same structure and tools.

We don't want to reinvent the wheel every time. What we want is consistent project structuring and code base formatting across projects and developers. We want high quality tools and optimal settings – and we don't want to spend time setting everything up for each project.

So we've created a tool that makes it quick and easy to set up well-structured projects in Python, our preferred language.

Meet Python Poetry Template for Copier – for a collection of high-quality plugins, settings, and workflows, curated by Flowtale.

What's the big deal?

When you're eager to get started on a new project, it can be tempting to just create a folder, add a Python file, and here we go.

But for any serious project, it will invariably lead to inefficiencies and limitations as the project grows. It's a case of 'one step in preparation saves two steps in execution'

You need to set up a good development environment, write boilerplate code, configure dependencies, and establish development guidelines. Additionally, there are many useful plugins that help with development, but they take time to set up.

Our Python Poetry Template lets you set up new projects in a few minutes. It automates secondary tasks that distract you from developing your idea, and comes with a selection of valuable plugins. Among other things, they help you

• Keep your code neat

• Apply common standards automatically

• Detect common bugs

For example, tools like formatters and linters maintain code quality by automatically formatting code and checking for errors, overall making the code easier to understand and maintain.

It doesn't just benefit the individual developer, but also greatly improves collaborative projects by ensuring code consistency across developers and teams.

Using a ready-made template doesn't replace all the work, and it requires some investment of time to understand and use. But we've done our best to document everything and automate the process, so you can learn by doing.

How it works

Copier is a tool for project scaffolding, which means setting up the basic structure of a software project.

It asks you a series of questions, such as your name, email, project name, which license you want to use, whether it's a command-line tool or a library, the testing framework, line length preferences, what editor you're using, etc.

Based on your responses, Copier automatically generates a folder structure populated with files that are named and configured according to your answers.

But Copier is just the shell. The real value lies in the templates – pre-defined development environments and the curation of plugins and settings they contain.

Let's look at what our Python Poetry Template has to offer.

Develop in Python, Flowtale-style

The Python Poetry Template helps our developers, especially those at a junior level, code more and configure less, channeling their efforts into building features and creating value.

The template contains a robust set of Python tools:

• Testing Framework: Integrates pytest and unittest which facilitate comprehensive and flexible testing approaches right out of the box.

• Pre-commit Hooks: Pre-commit automates the enforcement of code quality checks before commits are made, keeping the codebase clean and reducing the chance of introducing errors.

• Version Management: Employs bump2version for a simplified and automated versioning process, ensuring that the project's version number is consistently managed across releases.

• Common Style: Adopts EditorConfig to maintain consistent coding styles for all developers on the project, regardless of the editor or IDE they use.

• Editor Configuration: Configures VSCode with suggested extensions to enhance the development experience, ensuring that the setup is optimized and that developers have access to helpful linting and formatting tools.

• VSCode Dev Containers: Provides a fully configured development environment for Visual Studio Code that can be loaded with one click locally or spun up in the cloud directly from a GitHub repository thanks to Codespaces.

• Autoformatters: Enlists Black and isort to ensure that code adheres to PEP 8 guidelines, making the code readable and maintainable.

• Linters: Includes Flake8 and pydocstyle to examine the code for potential errors, enforce a common coding standard and docstring convention, and flag style issues.

• Test and Packaging: Sets up pipelines for continuous integration, automating tests and deployment tasks, which ensures that the code is tested in an isolated environment before it is merged into the main codebase.

I'm sold, how do I get started?

If you're anything like us, you appreciate a tutorial that gets you started in a few steps, instead of having to dig deep into the documentation. Well, here you go:

1. Install Copier

If you haven't already installed Copier, you can do so using pipx or pip.

pipx install copier
pip install copier

2. Run Copier to Create a Project

Use the Copier command to create a new project from the template. Replace my-new-project with the path where you want your new project to be created.

copier copy gh:flowtaleai/copier-python-poetry my-new-project

3. Answer Prompts

Copier will ask you a series of questions based on the template's configuration. Your answers will customize the project. For example, you might be asked to provide a project name, description, author name, etc. The full reference of the various options can be found here.

4. Initialize Version Control

Initialize a new Git repository.

cd my-new-project
git init
git add .
git commit -m "Initial commit"

5. Setup the project

make setup

6. Commit the lock file

git add poetry.lock
git commit -m "Poetry lock file regenerated"

Once the project is set up using the Copier template, you can immediately take advantage of some pre-configured features:

• make test launches the test suite, revealing a test that should pass out-of-the-box. This exemplifies how tests are integral to the project from the get-go, aligning with practices that encourage writing tests early in the development cycle.

• If you opted for a CLI during setup, mynewproject --help will display the help information for your project's command-line tool, indicating it's been installed and is ready to use following the make install command, which runs poetry install to set up the project environment.

We love making life easier for ourselves with tools that let us focus less on setting up environments and more on building cool AI projects.

Used right, our Python Poetry Template can do the same for you and the projects you're passionate about.

If you are interested in hearing more about our work, our development practices, or how we can help your organization, do reach out for a chat. Happy coding!