Including licences and writing READMEs

Developing Python Packages

James Fulton

Climate informatics researcher

Why do I need a license?

To give others permission to use your code

Open source licenses

Find more information here
Allow users to
- use your package
- modify your package
- distribute versions of your package

¹ https://choosealicense.com

What is a README?

The "front page" of your package
Displayed on Github or PyPI

What to include in a README

README sections

Title
Description and Features
Installation
Usage examples
Contributing
License

README format

Markdown (commonmark)

Contained in README.md file
Simpler
Used in this course and in the wild

reStructuredText

Contained in README.rst file
More complex
Also common in the wild

Commonmark

Contents of README.md

What it looks like when rendered

Commonmark

Contents of README.md

# mysklearn

mysklearn is a package for complete 
**linear regression** in Python.


You can find out more about this package 
on [DataCamp](https://datacamp.com)

What it looks like when rendered

mysklearn

mysklearn is a package for complete linear regression in python.

You can find out more about this package on DataCamp

Commonmark

Contents of README.md

# mysklearn

mysklearn is a package for complete 
**linear regression** in Python.


You can find out more about this package 
on [DataCamp](https://datacamp.com)


## Installation
You can install this package using

What it looks like when rendered

mysklearn

mysklearn is a package for complete linear regression in python.

You can find out more about this package on DataCamp

Installation

You can install this package using

Commonmark

Contents of README.md

# mysklearn
mysklearn is a package for complete 
**linear regression** in Python.

You can find out more about this package 
on [DataCamp](https://datacamp.com)

## Installation
You can install this package using

```
pip install mysklearn
```

What it looks like when rendered

mysklearn

mysklearn is a package for complete linear regression in python.

You can find out more about this package on DataCamp

Installation

You can install this package using

pip install mysklearn

Adding these files to your package

Directory tree for package with subpackages

mysklearn/
|-- mysklearn
|   |-- __init__.py
|   |-- preprocessing
|   |   |-- ...
|   |-- regression
|   |   |-- ...
|   |-- utils.py
|-- setup.py
|-- requirements.txt
|-- LICENSE      <--- new files
|-- README.md    <--- added to top directory

MANIFEST.in

Lists all the extra files to include in your package distribution.

MANIFEST.in

Contents of MANIFEST.in

include LICENSE
include README.md

mysklearn/
|-- mysklearn
|   |-- __init__.py
|   |-- preprocessing
|   |   |-- ...
|   |-- regression
|   |   |-- ...
|   |-- utils.py
|-- setup.py
|-- requirements.txt
|-- LICENSE
|-- README.md
|-- MANIFEST.in   <---

Let's practice!

Developing Python Packages