We need to answer the question - what is "building" a package

[lwasser]

i think it would be super helpful on the intro page of the package chapter to include a high level overview of the parts of a python package and what the build/ publish steps means / entails.

This doesn't have to be super involved but high level - perhaps a diagram with an explanation.

"these are the bare-min things that you need to do to create a python package" to really break down and describe the entire process.

[ucodery]

I attempted to define what "packaging" is in one of my talks, which seems to be the same question as here. My answer was simply that packaging was the act of taking a project and turning it into 1-N distributions. I then went on to further define these terms, but here we have precedence as the PyPA defines both project and distribution (but not either packaging or building) (https://packaging.python.org/en/latest/glossary/).

From this definition, I think that publishing is a distinct action that is not packaging, and I really don't think it fits inside building, but is still an important step for an author to understand and be able to perform if they want to share their code.

Is this what you had in mind for the intro page? I'm sure diagrams could be made, it is a simple flow.

[merwok]

I have made the same distinction in previous talks.
Packaging as a topic can be divided into separate actions: building (code into a distributable artifact), uploading (artifact to repository), installing (artifact from repository), and I think the last one was deploying (an app with dependencies).

[ucodery]

Indeed the package's journey continues past the act of packaging and even publishing. Another important step is solving, which determines if installing == deploying as you put it, or if deploying involves installing a tree of distributions. Solving is also responsible for choosing the specific distribution that is installed for a release, even after a version has been selected.

[merwok]

No, I meant that deploying is sending a full application somewhere. It’s separate entirely from uploading (sending a library somewhere so that people can make other libraries or applications).

[lwasser]

hey there - so sorry i missed this. so @agerber48 asked this question in the python discourse.

• this page - https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-distribution-files-sdist-wheel.html is helpful in explaining sdist vs wheel. but i think a high level overview mabe on our packging landing page here that describes what building is (for beginners) and i agree a diagram would be great of all of the components would be helpful. i could even see that diagram living on the home page of our packaging guide as well.

i'm very open to a PR - i can also help with the diagram graphics (we could make a nice diagram in google drawings even).

@merwok welcome to pyopensci!! how did you find us?

the goal of this guide is to be very beginner friendly.

so yes i could see something like this as a diagram:

write code / tests --> build into sdist/wheel - publish to pypi / conda-forge

something that really helps newer users understand what packaging is all about and then what that building step means without drowning them in too much detail if that makes sense?

[merwok]

This repo was linked from a discussion in the Python packaging forum! (discuss.python.org)

[ucodery]

I would be happy to help out with a diagram, but ISTM it would be largely (maybe entirely) a linear path. I think well-defined but approachable definitions is the more important point and that those definitions are right there with any graphic or description of the end-to-end process.

[ucodery]

This is essentially my view of "what is packaging" which is a superset of "what is building"

flowchart TD;
    A[Source] --->|build| B
    B[Distributions] --->|upload| C
    C[PyPI Project] --->|install| D[Package]

Loading

[lwasser]

@ucodery very cool graphic - how did you make it animated like that? i just added a note to add a paragraph with a graphic to this page of the guide in our google doc outline

@jagerber48 also pinging you as I know this was a topic brought up by you (i think??) on the Python discourse.

[lwasser]

i really like the idea of having a graph (horizontal would be better for our guide) that provides an overview of the process. high level. and we could also enhance it to add the elements of that "src" box. it would fit nicely on our build distribution type page at the tope because that page defines wheel vs SDist

[ucodery]

@lwasser I was using mermaid, in part because I thought it would allow better collaboration on the diagram. But I now realize you can't see the source of my comment! (if it was a checked-in md file you would see it render, and have the option to view raw)
This is what I wrote to get that image:

```mermaid
flowchart TD;
    A[Source] --->|build| B
    B[Distributions] --->|upload| C
    C[PyPI Project] --->|install| D[Package]
```

I would also prefer a horizontal flow, but I don't think mermaid gives that kind of control.

[NickleDave]

I am definitely not a mermaid expert but I think writing flowchart LR instead of flowchart TD will give you a left-to-right graph layout

That is,

```mermaid
flowchart LR;
    A[Source] --->|build| B
    B[Distributions] --->|upload| C
    C[PyPI Project] --->|install| D[Package]
```

gives you

flowchart LR;
    A[Source] --->|build| B
    B[Distributions] --->|upload| C
    C[PyPI Project] --->|install| D[Package]

Loading

(edit: sorry, I forgot how to nest code blocks)

(edit edit: and yes we could do this in a MyST doc -- https://mystmd.org/guide/diagrams)