Skip to content

Commit a51c1c2

Browse files
lwasserlwasser
committed
Fix: edits from review
1 parent da9994e commit a51c1c2

File tree

3 files changed

+114
-39
lines changed

3 files changed

+114
-39
lines changed

‎index.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# pyOpenSci Python Open Source Package Development Guide
22

3+
```{toctree}
4+
:hidden:
5+
:caption: Tutorials
6+
Tutorials <tutorials/intro>
7+
```
8+
39
```{toctree}
410
:hidden:
511
:caption: Documentation

‎tutorials/1-installable-code.md

Lines changed: 96 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,35 @@
1-
# Make your Python code pip installable
1+
# Make your Python code installable
22

3-
The first step in creating a Python package based on code that you
4-
have is to make that code pip installable. You will learn how to make
5-
your code pip installable in this lesson.
3+
In the previous lesson, you learned about both what a Python package is. You also learned about the [benefits of creating a Python
4+
package](tutorials/intro.html#why-create-a-python-package) including:
65

7-
<!--
8-
TODO: is it clear where to add commands? bash vs. python console
6+
* Being able to easily reuse in multiple workflows on your computer
7+
* Being able to share your code with others who may find the functionality useful.
8+
* Being able to better organize code that needs to be reused.
99

10+
11+
The first step in creating a Python package is turning that
12+
code into a Python package that is pip installable.
13+
The package that you create in this lesson will have
14+
the bare minimum elements that you need to install a package.
15+
16+
In upcoming lessons you will learn how to:
17+
* add a **README** file to support community use of your package
18+
* add package metadata in a **pyproject.toml** file to support publication to PyPI
19+
20+
:::{todo}
21+
22+
1. Is it clear where to add commands? bash vs. Python console
1023
Bash vs zsh is different
11-
does this work on windows and mac? i know it works on mac/linux
12-
-->
24+
2. Does this lesson run as expected on windows and mac?
25+
:::
26+
27+
:::{figure-md} code-to-python-package
1328

14-
:::{figure-md} code-to-script
29+
<img src="../images/tutorials/code-to-python-package.png" alt="Diagram showing the basic steps to creating an installable package. There are 4 boxes with arrows pointing towards the right. The boxes read, your code, create package structure, add metadata to pyproject.toml and pip install package." width="700px">
1530

16-
<img src="../images/tutorials/code-to-script-diagram.png" alt="Diagram showing the basic steps to creating an installable package. There are 4 boxes with arrows pointing towards the right. The boxes read, your code, create package structure, add metadata to pyproject.toml and pip install package." width="700px">
31+
A basic installable package needs a few things: code, a [specific package file structure](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html) and a `pyproject.toml` containing your package's name and version. Once you have these items in the correct directory structure, you can pip install your package into any environment on your computer.
1732

18-
A basic installable package needs a few things: code, a specific package structure and a `pyproject.toml` containing your package's name and version. Once you have these items in the correct directory structure, you can pip install your package into any environment on your computer.
1933
:::
2034

2135
:::{admonition} Learning Objectives
@@ -33,41 +47,58 @@ environment. You are welcome to use any environment manager that you choose.
3347

3448
* [If you need guidance creating a Python environment, review this lesson](extras/1-create-environment.md) which walks you through creating an environment using both `venv` and `conda`.
3549
* If you aren't sure which environment manager to use and
36-
you are a scientist, we suggest that you use `conda`.
50+
you are a scientist, we suggest that you use `conda`, particularly if you are working with any sort of spatial data.
3751
:::
3852

39-
## Make your package installable
53+
54+
55+
## Make a basic installable Python package
4056

4157

4258
:::{figure-md} packages-environment
4359

4460
<img src="../images/tutorials/environment-package-install.png" alt="This diagram has two smaller boxes with arrows pointing to the right to a python environment. The small boxes read your-package and pip install package. The environment box on the right reads - your python environment. It them lists your-package along with a few other core packages such as matplotlib, numpy, pandas, xarray and geopandas." width="700px">
4561

46-
Making your source code pip-installable is the first step towards creating a Python package. Once your code is pip-installable, it is a Python package and can be added to any Python environment on your computer and imported in the same way that you might import a package such as `Pandas` or `Geopandas`.
62+
Making your source code pip-installable is the first step towards creating a Python package. Once your code is pip-installable, it is a Python package and can be added to any Python environment on your computer and imported in the same way that you might import a package such as Pandas or GeoPandas.
4763
:::
4864

49-
## Make a basic Python package
50-
5165
It’s time to create the most basic version of a Python package.
52-
While this code can't be yet published to PyPI or conda and
53-
is not documented, it will be installable on your computer or
54-
anyone elses.
66+
67+
What you'll be able to do with this package at the end of this lesson is:
68+
69+
* Install it into any Python environment on your computer
70+
* If you share your code with someone else on GitHub or some other file/sharing or cloud based sharing platform, others will be able to install your package too.
71+
72+
While installable code is the first step towards making a Python package, there are some limitations. What you won't be able to do
73+
by the end of this lesson is publish your package to PyPI and then conda-forge.
74+
75+
The next 3 lessons in this series will teach you how to add the proper
76+
metadata and documentation that you will need to publish to PyPI.
77+
78+
:::{admonition} Installing packages from GitHub
79+
80+
If you wish to share your code without publishing to PyPI you can
81+
always install packages directly from GitHub using the syntax:
82+
83+
`pip install git+https://github.com/user/repo.git@branch_or_tag``
84+
85+
:::
5586

5687
### What does a basic package directory structure look like?
5788
To make your code installable you need:
5889

59-
- A `pyproject.toml` file
60-
- An (optional but recommended) `__init__.py` file in your code directory
61-
- A specific directory structure
90+
- A `pyproject.toml` file.
91+
- A specific directory structure.
6292
- Some code.
93+
- An `__init__.py` file in your code directory.
6394

6495
The directory structure you’ll create in this first section looks like this:
6596

6697
```bash
6798
pyospackage/
6899
└─ pyproject.toml
69-
└─ src/ # The src directory ensures your tests always run on the installed
70-
└── pyospackage/ # Package directory where code lives, use the package name
100+
└─ src/ # The source (src/) directory ensures your tests always run on the installed version of your code
101+
└── pyospackage/ # Package directory where code lives, use the package name
71102
├── __init__.py
72103
├── add_numbers.py
73104
└── # Add any other .py modules that you want here
@@ -79,40 +110,66 @@ Below, you will learn about each element of the above package structure.
79110

80111
Notice a few things about the above layout:
81112

82-
1. Your package code lives within a `src/packagename` directory. We suggest that you use `src/` directory as it ensure you are running tests on the installed version of your code. However, you are welcome to instead use a [flat layout](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html#about-the-flat-python-package-layout) which does not have a src/ directory at the root. [Learn more here.](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html#the-src-layout-and-testing)
83-
2. Within the `src/` directory you have a package directory called `pyospackage/`. Use the name of your package for that directory name.
84-
3. In your package directory, you have an `__init__.py` file and all of your Python modules.
85-
4. The `pyproject.toml` file lives at the root directory of your package.
86113

87-
## Init.py and pyproject.toml files
114+
1. Your package code lives within a `src/packagename` directory. We suggest that you use `src/` directory as it ensures that you are running tests on the installed version of your code. However, you are welcome to instead use a [flat layout](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html#about-the-flat-python-package-layout) which does not have a src/ directory at the root. [Learn more here.](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html#the-src-layout-and-testing)
115+
1. Within the `src/` directory you have a package directory called `pyospackage/`. Use the name of your package for that directory name.
116+
1. In your package directory, you have an `__init__.py` file and all of your Python modules.
117+
1. The `pyproject.toml` file lives at the root directory of your package.
118+
1. The name of the root directory for the package is **pyospackage** which is the name of the package. This is not a requirement but you will often see that the GitHub / GitLab repo and the root directory name are the same as the package name.
119+
120+
## __init__.py and pyproject.toml files
88121

89122
The `__init__.py` and `pyproject.toml` files in the above layout
90123
are important to understand. More on that below.
91124

92-
### What is an init.py file?
125+
### What is an __init__.py file?
126+
127+
When a directory contains an `__init__.py` file, it can be imported directly into Python.
128+
129+
For example, following the file structure example above which has an __init__.py file within it, you can run:
130+
131+
```
132+
import pyospackage
133+
```
134+
135+
The `__init__.py` file tells Python that a directory should be treated
136+
as a Python package.
137+
138+
139+
JEREMIAH - potentially remove init.py shortcutsl.... I'm not sure if these three points add anything for a beginner. I see a package already as organized modules, and that you get for free with an empty file. Also IIRC in slack we said that creating shortcuts in __init__.py can actually be harmful - probably not a tactic to start with. A version can go in __init__.py but also version strings as python data is a whole can of worms in python packaging.
93140

94-
The `__init__.py` file tells Python that the directory it’s in should be treated as a Python package.
95141
The `__init__.py` file also:
96142

97143
- Allows you to organize multiple modules within the package.
98-
- Allows you to create shortcuts for importing specific functions, and classes into your code (more on that later!)
144+
- Allows you to create shortcuts for importing specific functions and classes into your code (more on that later!)
99145
- Allows you to create a version object for people to call **version**
100146

101-
:::{admonition} The **init**.py file
147+
:::{admonition} The **__init__**.py file
102148
:class: tip
103149

104-
Since Python 3.3 came out, you can install a package without an `__init__.py` file. However, we suggest that you include it in your package structure as it allows you to customize your package’s user experience.
150+
The __init__.py file does not need to contain any code, it can be
151+
empty. Since Python 3.3 came out, you can install a package without an
152+
`__init__.py` file. However, we suggest that you include empty __init__.py files in your
153+
package structure as it allows you to customize your package’s user
154+
experience.
105155
:::
106156

157+
158+
> Perhaps the resolution is to be really clear that this is an overview and they'll learn more about all 3 things in later lessons? question about publication, etc
159+
107160
### What is a pyproject.toml file?
108161

109162
The **pyproject.toml** file is:
110163

111-
- Where you store your project’s metadata (including its name, authors, license, etc)
112-
- Where you store dependencies (the packages that it depends on)
113-
- Used to specify and configure what build back end you want to use to build your package distributions that are used for PyPI publication.
164+
- Where you define your project’s metadata (including its name, authors, license, etc)
165+
- Where you define dependencies (the packages that it depends on)
166+
- Used to specify and configure what build back end you want to use to [build your package](../package-structure-code/python-package-distribution-files-sdist-wheel).
114167

115-
After the `__init__.py` and `pyproject.toml` files have been added, your package can be built and distributed as an installable Python package using tools such as pip. Note that the `pyproject.toml` file needs to have the a few basic items defined for it to be installable including:
168+
After the `__init__.py` and `pyproject.toml` files have been added,
169+
your package can be built and distributed as an installable Python
170+
package using tools such as pip. Note that the `pyproject.toml` file
171+
needs to have a few basic items defined for the package to be
172+
installable including:
116173

117174
- The `build-backend` that you want to use,
118175
- The project `name` and `version`.
@@ -136,7 +193,7 @@ Neither 'setup.py' nor 'pyproject.toml' found.
136193

137194
Now that you understand the basics, it's time to create a Python package! Below you will create a directory structure similar to the structure described above.
138195

139-
If you don’t wish to create each of the files and directories below, you can always [fork and clone and customize the pyOpenSci example package, here.](https://github.com/pyOpenSci/pyosPackage)
196+
If you don’t wish to create each of the files and directories below, you can always [fork and clone and customize the pyOpenSci example package.](https://github.com/pyOpenSci/pyosPackage)
140197

141198
### Step 1: Set Up the Package Directory Structure
142199

‎tutorials/intro.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Python packaging 101
2+
3+
When we merge PR 1 this file will be updated with
4+
full content. please ignore for now it's a placeholder for the toctree
5+
6+
:::{toctree}
7+
:hidden:
8+
:caption: Python Packaging 101
9+
10+
What is a Python package? <self>
11+
Make your code pip installable <1-installable-code>
12+
:::

0 commit comments

Comments
 (0)