0x01 Introduction

The word ‘Sturcture’ here means how the files and folders are organized in the file system. What are the most important files should put in your project and why you need them. By understand this, you may find the best way to organise your codes and other related files effectively.

In this section, I will going to show some of the point you can concern when you are structing your project.

0x02 Structure of Repository.

Repository is the first thing you need to concern. When other people see your repository’s page they need to understand what is your project about and how to use it and so on. Hence, you should put a “README” file in your repository to help others understand your project better. Usually, “README” should also include enough details to help a new user get started, e.g. how to compile, how to install, and how to start integrating.

A README is a text file that introduces and explains a project. It contains information that is commonly required to understand what the project is about.

A good readme file for your project can have the following informations:

Project Titile: A little info about your project and/ or overview that explains what the project is about.
Motivation: Explain why you want to create this project.
Build Status: This is to maintain the further integration.
Screenshots: How’s does it look like, when your program is running.
Tech/framework used:Telling others the framework can give an idea for them to build similar project or even develop a better project based on this project.
Features: What your projet can do or help other finish their task?
Code Example: Giving some example can let people understand the coding process on how you develope your project.
Installation: This is the moset important part, you should teach your user on how to install it, if not they might even cant start using it.
API Reference: A quick and concise reference containing what you need to know to use a library or work with a program. It details functions, classes, return types, and more.
How to use: Telling user the best and right way to run your project
Contribute: If you want people contribute your project, you can include this section.
Credits: You can link to any post, people,tutorial that help you develope and contribute this project.
License: Including a proper software license can tells others what they can and can’t do with your project

One thing you should remember, it is not nessecry to inlude all the above information in your “README”. As longs as you can point out the main things that a user should know about project is enough, for the rest of the full details information you can put under your documentation or wiki.

Here are some guideline as well for writing a good “README”.

Sample Repository

Next, I will give an example of a python project repository.

README.rst
LICENSE
setup.py
requirements.txt
sample/__init__.py
sample/core.py
sample/helpers.py
docs/conf.py
docs/index.rst
tests/test_basic.py
tests/test_advanced.py

./sample.py or ./sample

Purpose: code of intrest. The source code that you use in your project.

Setup.py

setup.py is a python file, which usually tells you that the module/package you are about to install has been packaged and distributed with Distutils, which is the standard for distributing Python Modules. For more details, you can check here

./requirements.txt

A pip requirements file should be placed at the root of the repository. It should specify the dependencies required to contribute to the project: testing, building, and generating documentation.

If your project has no development dependencies, or you prefer development environment setup via setup.py, this file may be unnecessary.

./docs

This is the place to put your documentation of your project.

./test_basic.py or./test_advance.py

Purpose: Package integration and unit tests.

Starting out, a small test suite will often exist in a single file:

./test_sample.py

Once a test suite grows, you can move your tests to a directory, like so:

tests/test_basic.py
tests/test_advanced.py

In order to prevent keep importing the pakage modules whenever you are doing a testing, you can do it in this way.
Create a file call tests/context.py. This file allows you to modify the path for resolving the packaging issue.

import os
import sys

# set absolute path.
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))

import sample

Fianally, what you need to do is just add one line in each of your test.py. After that you can skip install the dependencies or pakage modules.
from .context import sample

.Makefile

Purpose: Defining generic tasks for your project.

A good makefile allow you to define the rules for your python file like which file need to pre-compile, recompile or even you can execute the shell script by using a makefile. The best part of using a makefile is to automate your code running. Once you done making your makefile, you only need to use the make command and easily run tests on your project.

Sample of Python makefile

.PHONY: test upload clean bootstrap

test:
	sh -c '. _virtualenv/bin/activate; nosetests tests'

test-all:
	tox

upload: test-all
	python setup.py sdist bdist_wheel upload
	make clean
	
register:
	python setup.py register

clean:
	rm -f MANIFEST
	rm -rf build dist
	
bootstrap: _virtualenv
	_virtualenv/bin/pip install -e .
ifneq ($(wildcard test-requirements.txt),) 
	_virtualenv/bin/pip install -r test-requirements.txt
endif
	make clean

_virtualenv: 
	virtualenv _virtualenv
	_virtualenv/bin/pip install --upgrade pip
_virtualenv/bin/pip install --upgrade setuptools

Learn more about makefile.

0x03 Structure of Code is Key

To be continue

量子雖然連肉眼都看不見，但卻有著無限的能量。

寫出優雅的Python代碼Part1 - Structuring Your Project