Creating a New Poetry Project

00:00 In the last lesson, you successfully installed Poetry. Now you and I are going to create a brand new Poetry project and explore the folders and files that comes with it.

00:10 First, navigate to the directory you’d like to use as your project’s workspace and open it within your code editor of choice. I’m currently within my workspace in my own code editor, Visual Studio Code, also known as VS Code.

00:23 Take a moment now to set that up in your own code editor. You can pause the video, set things up, and resume once you have set up and opened your workspace in your code editor.

00:34 If you followed the previous lesson, you should already have Poetry installed and ready to go. You can open and use any terminal of choice to interact with the code you’re going to be creating in your workspace.

00:46 I’ll be using VS Code’s built-in terminal throughout this course. To create a new Poetry project, first, get a name for your project. You can use whatever valid name you’d like or follow along with mine.

00:58 Then, you’re going to use the poetry new command. For instance, if you want to name it rp-poetry for Real Python Poetry, you’ll type in the command poetry new rp-poetry and then press Enter.

01:15 This should create a new Poetry project. Here in my terminal, I see Created Package rp_poetry in rp-poetry. Following the project name I specified, this command creates a directory named rp-poetry and with it some files and folders. You and I will explore and understand these created files and folders next. Once you create your project, Poetry generates a basic folder structure that should look something like this.

01:50 Inside your project directory, you get an rp_poetry folder. This folder is to contain your project’s main code files the __init__.py file or, the dunder init, as it’s popularly called, makes this folder a Python package.

02:07 Next, you have a tests/ folder. This is where you can add unit tests for your project if needed. Next, a README.md file for project documentation and then a pyproject.toml file.

02:21 This is one of the most important files. It holds your project’s metadata, dependencies, and main configuration. You’ll explore the contents of this file later.

02:32 If you look closely, you’ll notice that Poetry translated the dash in the project name we’ve provided into an underscore in the rp_poetry package that got created in our project.

02:44 This normalization ensures that the name is a valid Python identifier as dashes are interpreted as the minus operator and might cause some issues if used as a package name.

02:54 So rp-poetry wouldn’t be a valid identifier.

02:59 If you want more control over the package name, you can use the --name flag to specify a different name for the Python package that will be created in your project.

03:10 One thing to note is that Poetry will still normalize the package name you specify if there is still a dash in it.

03:18 Let’s discuss another way to structure your project. By default, Poetry follows what we call a flat layout where your Python package resides at the root level of the project directory.

03:30 If you prefer to arrange things a little differently and have your code in its source directory, you can use the --src or the double dash source flag when creating the project.

03:42 This command generates a structure that will look something like this. The files are mostly the same, just that the Python package and your other main code files will now reside in a src/ parent directory instead. If you want to give this a try, you can create another project, but in your poetry new command, you’ll add the --src flag, like this: poetry new rp-poetry --src.

04:10 You should then see a slightly different source directory with the Python package and other files created as you had before.

04:18 Both the flat and source directory layouts have their advantages and disadvantages, and it’s a matter of preference. You can explore more on your own by reading the Python packaging guide. Link to that is provided in the description of this video.

04:32 The src layout is typically ideal for larger long-term projects where you need a clear separation of concerns and more structure to your project.

04:40 While the flat layout can be quicker to set up and is often used for smaller to medium-sized projects or for quick prototypes. For the purpose of this course, you and I can stick to the default flat layout to work with our Poetry projects.

04:55 You have just explored ways to create a new project with Poetry, which sets up a basic structure for you to build on. In the next lesson, you and I will dive deep into the pyproject.toml file that gets created by Poetry, exploring its content, and learn how to configure your project’s dependencies with it.