From 6248c90ca6fb91758524addf69a4a179c06baf3d Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Thu, 4 Jun 2020 14:28:21 +0200 Subject: [PATCH 01/21] step 1 - add the outline files --- .gitignore | 7 ++++++ CHANGELOG.md | 8 +++++++ LICENSE | 21 ++++++++++++++++ MANIFEST.in | 1 + Makefile | 36 ++++++++++++++++++++++++++++ README.rst | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++ setup.py | 26 ++++++++++++++++++++ 7 files changed, 167 insertions(+) create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 LICENSE create mode 100644 MANIFEST.in create mode 100644 Makefile create mode 100644 README.rst create mode 100644 setup.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..518e1e6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +*#*# +*~ +*pyc +*.egg-info +build +dist +docs/build diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..11bddf3 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,8 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..dfe641e --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2020 Alessandra Bilardi + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..9561fb1 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1 @@ +include README.rst diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..6bb8e98 --- /dev/null +++ b/Makefile @@ -0,0 +1,36 @@ +# Python prototype makefile + +PACKAGE_NAME = "simple-sample" +YOUR_USERNAME = "bilardi" + +.PHONY: help # print this help list +help: + grep PHONY Makefile | sed 's/.PHONY: /make /' | grep -v grep + +.PHONY: unittest # run unit tests +unittest: + python3 -m unittest discover -v + +.PHONY: clean # remove packaging files +clean: + rm -rf build dist *.egg-info; rm -rf */*pyc; rm -rf */*/*pyc; rm -rf */__pycache__ + +.PHONY: doc # build documentation +doc: + cd docs; make html; cd - + +.PHONY: buildtest # build package on testpypi +buildtest: clean + python3 setup.py sdist bdist_wheel; python3 -m twine upload --repository testpypi dist/* + +.PHONY: installtest # install package from testpypi +installtest: + mkdir -p test; cd test; python3 -m pip install --upgrade --index-url https://test.pypi.org/simple/ --no-deps $(PACKAGE_NAME)-$(YOUR_USERNAME); cd - + +.PHONY: build # build package on pypi +build: clean + python3 setup.py sdist bdist_wheel; python3 -m twine upload dist/* + +.PHONY: install # install package from pypi +install: + python3 -m pip install --upgrade $(PACKAGE_NAME) diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..8060de6 --- /dev/null +++ b/README.rst @@ -0,0 +1,68 @@ +Python prototype +================ + +This package contains a simple sample of a Python package prototype. +It is part of the `educational repositories `_ to learn how to write stardard code and common uses of the TDD. + +See the documentation and how to do it on `readthedocs `_. +And see the development of this code step by step + +* with `see-git-steps `_ +* on `readthedocs/stepbystep `_ + +Installation +############### + +The package is self-consistent. So you can download the package by github: + +.. code-block:: bash + + $ git clone https://github.com/bilardi/python-prototype + +Or you can install by python3-pip: + +.. code-block:: bash + + $ pip3 install simple_sample + +Usage +##### + +Read the unit tests in `tests/testMyClass.py `_ file to use it. This is a best practice. +You can read also the documentation by command line, if you download by github + +.. code-block:: bash + + $ python3 + >>> from simple_sample.myClass import MyClass + >>> print(MyClass.__doc__) + >>> help(MyClass) + >>> quit() + +If you want to see the local documentation, that you have downloaded by github, you can use the same steps but before you must to change the directory + +.. code-block:: bash + + $ cd python-prototype + +Development +########### + +It is common use to test the code step by step and unittest module is a good beginning for unit test and functional test. + +Test with unittest module + +.. code-block:: bash + + $ cd python-prototype + $ python3 -m unittest discover -v + +Change Log +########## + +See `CHANGELOG.md `_ for details. + +License +####### + +This package is released under the MIT license. See `LICENSE `_ for details. diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..2e72bee --- /dev/null +++ b/setup.py @@ -0,0 +1,26 @@ +import setuptools + +setuptools.setup( + name="simple-sample", + version="0.0.1", + author="Alessandra Bilardi", + author_email="alessandra.bilardi@gmail.com", + description="A simple sample of a Python package prototype", +# long_description=open('README.md').read(), +# long_description_content_type="text/markdown", + long_description=open('README.rst').read(), + long_description_content_type="text/x-rst", + url="https://simple-sample.readthedocs.io/", + packages=setuptools.find_packages(), + classifiers=[ + "Programming Language :: Python :: 3", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + ], + python_requires='>=3.6', + project_urls={ + "Source":"https://github.com/bilardi/python-prototype", + "Bug Reports":"https://github.com/bilardi/python-prototype/issues", + "Funding":"https://donate.pypi.org", + }, +) From 57e2d766fbdea1d6a3862676f6f3a28e5ab5746c Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Thu, 4 Jun 2020 17:54:41 +0200 Subject: [PATCH 02/21] step 2 - add the empty package version --- setup.py | 5 +++-- simple_sample/__init__.py | 17 +++++++++++++++++ tests/__init__.py | 0 3 files changed, 20 insertions(+), 2 deletions(-) create mode 100644 simple_sample/__init__.py create mode 100644 tests/__init__.py diff --git a/setup.py b/setup.py index 2e72bee..ad0f529 100644 --- a/setup.py +++ b/setup.py @@ -1,9 +1,10 @@ import setuptools +import simple_sample setuptools.setup( name="simple-sample", - version="0.0.1", - author="Alessandra Bilardi", + version=simple_sample.__version__, + author=simple_sample.__author__, author_email="alessandra.bilardi@gmail.com", description="A simple sample of a Python package prototype", # long_description=open('README.md').read(), diff --git a/simple_sample/__init__.py b/simple_sample/__init__.py new file mode 100644 index 0000000..e74429a --- /dev/null +++ b/simple_sample/__init__.py @@ -0,0 +1,17 @@ +"""An example of package + +This package contains an example of module like a prototype that you can follow for yours. +The package is self-consistent: it contains three classes and some unit tests. +It is part of the educational repositories (https://github.com/pandle/materials) +to learn how to write stardard code and common uses of the TDD. + +Package contents three files, and each file contains one class with the same name. + + >>> import simple_sample.myClass + >>> help(simple_sample.myClass) + +# license MIT +# support https://github.com/bilardi/python-prototype/issues +""" +__version__ = '0.0.1' +__author__ = 'Alessandra Bilardi' diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..e69de29 From 89c4563c7bdcbe5f50fd153c078aa813846cfd09 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Thu, 4 Jun 2020 17:58:38 +0200 Subject: [PATCH 03/21] step 3 - add documentation by sphinx --- CHANGELOG.md | 10 ++++ README.rst | 4 +- docs/Makefile | 20 ++++++++ docs/make.bat | 35 +++++++++++++ docs/source/conf.py | 58 +++++++++++++++++++++ docs/source/howtomake.rst | 72 ++++++++++++++++++++++++++ docs/source/howtouse.rst | 75 +++++++++++++++++++++++++++ docs/source/index.rst | 25 +++++++++ docs/source/overview.rst | 1 + docs/source/stepbystep.rst | 102 +++++++++++++++++++++++++++++++++++++ 10 files changed, 400 insertions(+), 2 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/howtomake.rst create mode 100644 docs/source/howtouse.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/overview.rst create mode 100644 docs/source/stepbystep.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index 11bddf3..3ae69bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,3 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] + +## [0.0.1] - 2020-06-04 + +### Added +- the outline files +- the init files of package and tests +- the documentation by sphinx + +[Unreleased]: https://github.com/bilardi/python-prototype/compare/v0.0.1...HEAD +[0.0.1]: https://github.com/bilardi/python-prototype/releases/tag/v0.0.1 diff --git a/README.rst b/README.rst index 8060de6..2cc559c 100644 --- a/README.rst +++ b/README.rst @@ -8,7 +8,7 @@ See the documentation and how to do it on `readthedocs `_ -* on `readthedocs/stepbystep `_ +* on `readthedocs / step by step `_ Installation ############### @@ -29,7 +29,7 @@ Usage ##### Read the unit tests in `tests/testMyClass.py `_ file to use it. This is a best practice. -You can read also the documentation by command line, if you download by github +You can read also the documentation by command line, .. code-block:: bash diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..6cf9e13 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,58 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'simple-sample' +copyright = '2020, Alessandra Bilardi' +author = 'Alessandra Bilardi' + +# The full version, including alpha/beta/rc tags +version = '0.0.1' +release = '0.0.1' + +# specify the master doc, otherwise the build at read the docs fails +master_doc = 'index' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/docs/source/howtomake.rst b/docs/source/howtomake.rst new file mode 100644 index 0000000..8d73d50 --- /dev/null +++ b/docs/source/howtomake.rst @@ -0,0 +1,72 @@ +How to make +=========== + +In this section you can find how to generate or publish that helps you with managing your code. + +Virtual environment +################### + +When you have to install specific requirements.txt, you can use a `virtual environment `_: this method is important to test different packages versions without to install them on your local. + +The main commands are + +.. code-block:: bash + + $ cd python-prototype + $ python3 -m venv .env # create virtual environment + $ source .env/bin/activate # enter in the virtual environment + $ pip install --upgrade -r requirements.txt # install your dependences + $ deactivate # exit when you will have finished the job + $ rm -rf .env # remove the virtual environment it is a best practice + +Documentation +############# + +The Python language is permissive, but if you use a basic documentation like `Python Enhancement Proposals 8 `_ (PEP-8) and unit / functional test, everyone can easily read your code. There are many style to write `Python documentation `_. + +If you load your package on `GitHub `_, `GitLab `_, or `BitBucket `_, you can also use `sphinx `_ for creating docs folder like in this package. It can help you to organize concepts in an unique place without duplicates: the README.rst is the homepage on Github and Pypi repositories and it is also one of these pages (see `overview.rst `_). + +The main commands for building documentation are + +.. code-block:: bash + + $ pip3 install sphinx + $ pip3 install sphinx_rtd_theme # it is necessary only if you want the theme sphinx_rtd_theme + $ cd python-prototype/docs/ + $ sphinx-quickstart + $ make html + +And you can open build/html/index.html in your web browser to see your docs. + +Instead, for uploading documentation on readthedocs, you have to follow `this guide `_. + +TDD +### + +Before write code, it is important to verbalize the concepts by documentation and to create Test Driven Development (TDD) for your code. Then, it is important to use unit test for finding the issues and before to update change log file and package version. + +See the development of this code step by step on `readthedocs / step by step `_ for learning how to make a unit test. + +Packaging +######### + +The tutorial for `packaging your projects `_ is standard. And then your package is public on `PyPI `_. + +The main commands for testing are + +.. code-block:: bash + + $ rm -rf build dist *.egg-info + $ python3 setup.py sdist bdist_wheel # create source archive + $ python3 -m twine upload --repository testpypi dist/* # upload source archive on testpypi + $ python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps simple-sample-bilardi # install package from testpypi + +The main commands for the production environment are + +.. code-block:: bash + + $ rm -rf build dist *.egg-info + $ python3 setup.py sdist bdist_wheel # create source archive + $ python3 -m twine upload dist/* # upload source archive on pypi + $ python3 -m pip install simple-sample # install package from pypi + $ pip3 install simple-sample # slim command for installing the package diff --git a/docs/source/howtouse.rst b/docs/source/howtouse.rst new file mode 100644 index 0000000..5250a23 --- /dev/null +++ b/docs/source/howtouse.rst @@ -0,0 +1,75 @@ +How to use +========== + +In this section you can find some tips & tricks for learning to use any code. + +Unit tests +########## + +When you change something on your code, you can run one unit test about that class changed + +.. code-block:: bash + + $ cd python-prototype + $ python3 -m unittest -v tests/testMyClass.py + +And when you are ready for the commit, you can use a command for running all unit tests + +.. code-block:: bash + + $ cd python-prototype + $ python3 -m unittest discover -v + +But for learning how to use an class in your code, you need to read its unit test file. +You can find the import class, the initialization class, and the main public methods. + +Documentation +############# + +Another approach is to read the documentation in the class file. When you install a package, you can also read its documentation by shell + +.. code-block:: bash + + $ python3 + >>> import simple_sample + >>> print(simple_sample.__doc__) # description like overview of the package + >>> help(simple_sample) # description of the package contents, and if there are, classes and functions + >>> quit() + +In the description, you can find an example for a command that you can use for each package element + +.. code-block:: bash + + $ python3 + >>> import simple_sample.myClass + >>> print(simple_sample.myClass.__doc__) # description like overview of the element + >>> help(simple_sample.myClass) # description of the element contents: classes and functions + >>> quit() + +If there are more classes in an package element, you can import a specific class where to read all methods + +.. code-block:: bash + + $ python3 + >>> from simple_sample.myClass import MyClass + >>> print(MyClass.__doc__) # description like overview of the class + >>> help(MyClass) # description of the class contents: methods, and if there are, functions + >>> quit() + +MyClass +####### + +The precedent approches are the best practice for learning something about a specific package. + +Sometimes, the package is so complex, that it is also necessary a "Quick start" where a developer can learn the main classes or methods to start from + +.. code-block:: bash + + $ python3 + >>> from simple_sample.myClass import MyClass + >>> mc = MyClass() # initialization with or without boolean argument + >>> mc.foo(True); # returns the reverse value + >>> mc.bar(); # returns the boolean initialized + >>> mc.foobar(); # returns the reverse value of the boolean initialized + >>> quit() + diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..bdeb05f --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,25 @@ +.. simple-sample documentation master file, created by + sphinx-quickstart on Mon Jun 4 06:16:25 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to simple-sample's documentation! +========================================= + +This package contains a simple sample of a Python package prototype. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview + howtouse + howtomake + stepbystep + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/overview.rst b/docs/source/overview.rst new file mode 100644 index 0000000..38ba804 --- /dev/null +++ b/docs/source/overview.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst \ No newline at end of file diff --git a/docs/source/stepbystep.rst b/docs/source/stepbystep.rst new file mode 100644 index 0000000..6915947 --- /dev/null +++ b/docs/source/stepbystep.rst @@ -0,0 +1,102 @@ +Step by step +============================ + +This page is for learning all steps that they are necessary for writing a simple package like simple-sample. + +see-git-steps +############# + +The package `see-git-steps `_ has been written for reading piece by piece the commits of a git repository. + +If you want to use it, you have to install it following its README.md. + +Getting started +############### + +The goal of the package simple-sample is to create a Python package prototype. +So you can use this simple package for downloading a base for your package. + +Step 1 +****** + +The first step is to add all the outline files for your package + +.. code-block:: bash + + $ cd python-prototype + $ see-git-steps + 6248c90ca6fb91758524addf69a4a179c06baf3d step 1 - add the outline files + .gitignore + CHANGELOG.md + LICENSE + MANIFEST.in + Makefile + README.rst + setup.py + +They are important files and below you can find a link of a guide for each file + +* `.gitignore `_, to ignore specific files when you have to commit +* `CHANGELOG.md `_, the best practise for reading the minor o major change of your code +* `LICENSE `_, the best practise for defining your policy for the public repository +* `MANIFEST.in `_, documentation included into your package +* `Makefile `_, it is not necessary but it is a comfortable way to remember procedures +* `README.rst `_, documentation visible on your repository homepage +* `setup.py `_, it is a best practise for creating or installing your package + +The files that you have to customize are + +* **.gitignore**, for example, if you use an ide with specific files extension +* **LICENSE**, with year and your name +* **Makefile**, with your PACKAGE_NAME and YOUR_USERNAME of `PyPI `_ +* **README.rst**, with your quick start documentation +* **setup.py**, where you find some variables: name, author, author_email, description and urls + +When you have modified, you can commit your first change + +.. code-block:: bash + + $ cd python-prototype + $ git init # for initializing the repository + $ git add .gitignore CHANGELOG.md LICENSE MANIFEST.in Makefile README.rst setup.py + $ git commit -m "step 1 - add the outline files" + +Step 2 +****** + +The second step is to add the first files that you need for creating your package + +.. code-block:: bash + + $ cd python-prototype + $ see-git-steps + 57e2d766fbdea1d6a3862676f6f3a28e5ab5746c step 2 - add the empty package version + setup.py + simple_sample/__init__.py + tests/__init__.py + +The files `__init__.py `_ are the base of a regular package. + +It can be empty, like **tests/__init__.py**, and it will say anyway that folder is a package. + +It can contain some code, like `simple_sample/__init__.py `_, and it is sufficient for importing it in setup.py for recovering author and version of the package. + +See the changes of **setup.py** by `GitHub `_ or by command line with see-git-steps + +.. code-block:: bash + + $ cd python-prototype + $ see-git-steps -c 57e2d766fbdea1d6a3862676f6f3a28e5ab5746c -v + +When you have modified **setup.py** and added the new files, you can commit your changes + +.. code-block:: bash + + $ cd python-prototype + $ git add setup.py tests/__init__.py simple_sample/__init__.py + $ git commit -m "step 2 - add the empty package version" + +Step 3 +****** + +To be continued .. \ No newline at end of file From 190b5d704c7d1bf3104ce86558107cf6c37e02c0 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 22:26:14 +0200 Subject: [PATCH 04/21] Update documentation --- docs/source/stepbystep.rst | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/source/stepbystep.rst b/docs/source/stepbystep.rst index 6915947..9ba1a54 100644 --- a/docs/source/stepbystep.rst +++ b/docs/source/stepbystep.rst @@ -99,4 +99,39 @@ When you have modified **setup.py** and added the new files, you can commit your Step 3 ****** +Before write code, it is important to verbalize the concepts by documentation: +so the documentation is important to learn a package as to plan how to write the code. + +You can write your documentation as you want: you can create docs folder like in this package, by `sphinx `_. + +When you have created your documentation, you can add the new folder and you can commit your changes + +.. code-block:: bash + + $ cd python-prototype + $ git add docs + $ git commit -m "step 3 - add documentation by sphinx" + +When a commit completes one feature or a set of fixies, you can tag that commit as a release. +The standard behaviour is to add changes in a CHANGELOG file: see the changes of **CHANGELOG.md** by `GitHub `_ or by command line with see-git-steps + +.. code-block:: bash + + $ cd python-prototype + $ see-git-steps -c 20b91ae691f29c96059dc3d3b355ab7c91eb9928 -v | head -n 21 + +So you can add CHANGELOG.md on your last commit, or you can create one commit for changelog, and then you can add the tag. + +.. code-block:: bash + + $ cd python-prototype + $ git add CHANGELOG.md + $ git commit --amend # add file on your last commit + $ git tag -d v0.0.1 -m "Empty package and documentation by sphinx" # create a tag with that version name + $ git tag -n # show the tag list with description + $ git push origin --tags # load the tag on repository + +Step 4 +****** + To be continued .. \ No newline at end of file From b31157739997841621968440f970778059a41946 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 22:26:38 +0200 Subject: [PATCH 05/21] step 4 - add the unit test for MyClassInterface --- tests/testMyClassInterface.py | 48 +++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100755 tests/testMyClassInterface.py diff --git a/tests/testMyClassInterface.py b/tests/testMyClassInterface.py new file mode 100755 index 0000000..fae8c2f --- /dev/null +++ b/tests/testMyClassInterface.py @@ -0,0 +1,48 @@ +"""Test class of MyClassInterface + +This is a basic unit test class. There is a test for each public function. +If the functions contained conditions, there would be more tests for each public function. + +# license MIT +# author Alessandra Bilardi +# see https://github.com/bilardi/python-prototype for details +""" + +import unittest +from simple_sample.myClassInterface import MyClassInterface + +class TestMyClassInterface(unittest.TestCase, MyClassInterface): + """ + This is a basic unit test class. There is a test for each public function. + If the functions contained conditions, there would be more tests for each public function. + """ + # mci(MyClassInterface): a class variable with default None + mci = None + def __init__(self, *args, **kwargs): + """ + Initialization of variables + """ + self.mci = MyClassInterface() + unittest.TestCase.__init__(self, *args, **kwargs) + + def test_my_class_interface_can_be_created(self): + """ + Verifies if the class MyClassInterface can be created + """ + self.assertTrue(isinstance(self.mci, MyClassInterface)) + + def test_my_class_interface_gets_bar_value(self): + """ + Verifies if the class MyClassInterface bar method return None + """ + self.assertIsNone(self.mci.bar()) + + def test_my_class_interface_gets_qux_value(self): + """ + Verifies if the class MyClassInterface qux method raises an exception + """ + with self.assertRaises(NotImplementedError): + self.mci.qux() + +if __name__ == '__main__': + unittest.main() From 46bc250c33b3264461a0aff69a21cd791b143940 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 22:39:46 +0200 Subject: [PATCH 06/21] Update documentation --- docs/source/stepbystep.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/source/stepbystep.rst b/docs/source/stepbystep.rst index 9ba1a54..c4a8929 100644 --- a/docs/source/stepbystep.rst +++ b/docs/source/stepbystep.rst @@ -134,4 +134,28 @@ So you can add CHANGELOG.md on your last commit, or you can create one commit fo Step 4 ****** +Before write code, it is important to verbalize the methods by create Test Driven Development (TDD) for your code. +Then, it is important to use unit test for finding the issues and before to update change log file and package version. + +In Python, a standard TDD is offered by unittest module: see the unit tests of MyClassInterface by `GitHub `_ or by command line with see-git-steps + +.. code-block:: bash + + $ cd python-prototype + $ see-git-steps -c b31157739997841621968440f970778059a41946 -v + +In Python, the interface is not necessary, but this is a simple sample with a bit of everything. +The MyClassInterface will have only 2 methods not defined in two different ways: one using **pass** and one using **raise**. + +When you have created **tests/testMyClassInterface.py** and added the new files, you can commit your changes + +.. code-block:: bash + + $ cd python-prototype + $ git add tests/testMyClassInterface.py + $ git commit -m "step 4 - add the unit test for MyClassInterface" + +Step 5 +****** + To be continued .. \ No newline at end of file From 31b35d60e49878aa01fd8d7d6c47200d8696523b Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 22:43:14 +0200 Subject: [PATCH 07/21] step 5 - add MyClassInterface and unit tests works properly --- simple_sample/myClassInterface.py | 35 +++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100755 simple_sample/myClassInterface.py diff --git a/simple_sample/myClassInterface.py b/simple_sample/myClassInterface.py new file mode 100755 index 0000000..6277668 --- /dev/null +++ b/simple_sample/myClassInterface.py @@ -0,0 +1,35 @@ +"""An example of interface class + +An example of interface class, but interfaces are not necessary in Python. +There are two examples of methods without implementation: bar returns None and qux returns an exception. + +# license MIT +# author Alessandra Bilardi +# see https://github.com/bilardi/python-prototype for details +# cite https://stackoverflow.com/questions/2124190/how-do-i-implement-interfaces-in-python/2124415#2124415 + +Interfaces are not necessary in Python. This is because Python has proper multiple inheritance, +and also ducktyping, which means that the places where you must have interfaces in Java, +you don't have to have them in Python. +""" + +class MyClassInterface(): + """ + An example of interface class. Interfaces are not necessary in Python. + There are two examples of methods without implementation: bar returns None and qux returns an exception. + """ + def bar(self) -> bool: + """ + Bar + Returns: + A boolean value + """ + pass + + def qux(self) -> bool: + """ + Qux + Returns: + A boolean value + """ + raise NotImplementedError From b16f0a5bfaf14a87eb98df74bde2f8711526ee22 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 23:01:35 +0200 Subject: [PATCH 08/21] Update documentation --- docs/source/stepbystep.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/source/stepbystep.rst b/docs/source/stepbystep.rst index c4a8929..db2df4b 100644 --- a/docs/source/stepbystep.rst +++ b/docs/source/stepbystep.rst @@ -158,4 +158,38 @@ When you have created **tests/testMyClassInterface.py** and added the new files, Step 5 ****** +Now you can write your first class: see MyClassInterface by `GitHub `_ or by command line with see-git-steps + +.. code-block:: bash + + $ cd python-prototype + $ see-git-steps -c 31b35d60e49878aa01fd8d7d6c47200d8696523b -v + +When you have created **simple_sample/myClassInterface.py**, you can run the unit tests of MyClassInterface + +.. code-block:: bash + + $ cd python-prototype + $ python3 -m unittest discover -v + test_my_class_interface_can_be_created (tests.testMyClassInterface.TestMyClassInterface) ... ok + test_my_class_interface_gets_bar_value (tests.testMyClassInterface.TestMyClassInterface) ... ok + test_my_class_interface_gets_qux_value (tests.testMyClassInterface.TestMyClassInterface) ... ok + + ---------------------------------------------------------------------- + Ran 3 tests in 0.000s + + OK + +It is a best practise to run unit tests after a change and before a commit. +If the result is like the example (all tests are OK), you can add the new files and you can commit your changes + +.. code-block:: bash + + $ cd python-prototype + $ git add simple_sample/myClassInterface.py + $ git commit -m "step 5 - add MyClassInterface and unit tests works properly" + +Step 6 +****** + To be continued .. \ No newline at end of file From fcec3fca61c7860a63969c6b6e56d951ab187489 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 23:10:17 +0200 Subject: [PATCH 09/21] step 6 - add the unit test for MyClassAbstract --- tests/testMyClassAbstract.py | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100755 tests/testMyClassAbstract.py diff --git a/tests/testMyClassAbstract.py b/tests/testMyClassAbstract.py new file mode 100755 index 0000000..a5660e2 --- /dev/null +++ b/tests/testMyClassAbstract.py @@ -0,0 +1,35 @@ +"""Test class of MyClassAbstract + +This is a basic unit test class. +It is not possible to instantiate a class with an abstract method, +so missing the method for testing the other method. + +# license MIT +# author Alessandra Bilardi +# see https://github.com/bilardi/python-prototype for details +""" + +import unittest +from simple_sample.myClassAbstract import MyClassAbstract + +class TestMyClassAbstract(unittest.TestCase): + """ + This is a basic unit test class. + It is not possible to instantiate a class with an abstract method, + so missing the method for testing the other method. + """ + def __init__(self, *args, **kwargs): + """ + Initialization of variables + """ + unittest.TestCase.__init__(self, *args, **kwargs) + + def test_my_class_abstract_can_be_created(self): + """ + Verifies if the class MyClassAbstract raises an exception + """ + with self.assertRaises(TypeError): + MyClassAbstract() + +if __name__ == '__main__': + unittest.main() From 8a8f0c961b0d2fbc3cdbf6d45168fd1b0821a26a Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 23:19:40 +0200 Subject: [PATCH 10/21] Update documentation --- docs/source/stepbystep.rst | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/source/stepbystep.rst b/docs/source/stepbystep.rst index db2df4b..d63b356 100644 --- a/docs/source/stepbystep.rst +++ b/docs/source/stepbystep.rst @@ -147,7 +147,7 @@ In Python, a standard TDD is offered by unittest module: see the unit tests of M In Python, the interface is not necessary, but this is a simple sample with a bit of everything. The MyClassInterface will have only 2 methods not defined in two different ways: one using **pass** and one using **raise**. -When you have created **tests/testMyClassInterface.py** and added the new files, you can commit your changes +When you have created **tests/testMyClassInterface.py** and added the new file, you can commit your changes .. code-block:: bash @@ -181,7 +181,7 @@ When you have created **simple_sample/myClassInterface.py**, you can run the uni OK It is a best practise to run unit tests after a change and before a commit. -If the result is like the example (all tests are OK), you can add the new files and you can commit your changes +If the result is like the example (all tests are OK), you can add the new file and you can commit your changes .. code-block:: bash @@ -192,4 +192,23 @@ If the result is like the example (all tests are OK), you can add the new files Step 6 ****** +If you need to use a framework, abstract class is a good method. The peculiarity of this is that it cannot be imported. +So the unit tests are simple: see the unit tests of MyClassAbstract by `GitHub `_ or by command line with see-git-steps + +.. code-block:: bash + + $ cd python-prototype + $ see-git-steps -c fcec3fca61c7860a63969c6b6e56d951ab187489 -v + +When you have created **tests/testMyClassAbstract.py** and added the new file, you can commit your changes + +.. code-block:: bash + + $ cd python-prototype + $ git add tests/testMyClassAbstract.py + $ git commit -m "step 6 - add the unit test for MyClassAbstract" + +Step 7 +****** + To be continued .. \ No newline at end of file From ddb120bd0c14528b0c8b0caf223b387588725c50 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 23:20:33 +0200 Subject: [PATCH 11/21] step 7 - add MyClassAbstract and unit tests works properly --- simple_sample/myClassAbstract.py | 49 ++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100755 simple_sample/myClassAbstract.py diff --git a/simple_sample/myClassAbstract.py b/simple_sample/myClassAbstract.py new file mode 100755 index 0000000..d6b057c --- /dev/null +++ b/simple_sample/myClassAbstract.py @@ -0,0 +1,49 @@ +"""An example of abstract class + +An example of abstract class. If you need to use a framework, abstract class is a good method. +There is a random boolean by baz function and an abstract method named foo function. +It is not possible to instantiate a class with an abstract method. +And it is not possible to have an abstract method protected: it will be changed in a pubilc method. + +# license MIT +# author Alessandra Bilardi +# see https://github.com/bilardi/python-prototype for details +# cite https://www.python.org/dev/peps/pep-3119/ + +Much of the thinking that went into the proposal is not about the specific mechanism of ABCs, +as contrasted with Interfaces or Generic Functions (GFs), but about clarifying philosophical issues +like "what makes a set", "what makes a mapping" and "what makes a sequence". +ABCs are intended to solve problems that don't have a good solution at all in Python 2, +such as distinguishing between mappings and sequences. +""" + +from abc import ABCMeta, abstractmethod +import random + +class MyClassAbstract(metaclass=ABCMeta): + """ + An example of abstract class. If you need to use a framework, abstract class is a good method. + There is a random boolean by baz function and an abstract method named foo function. + It is not possible to instantiate a class with an abstract method. + And it is not possible to have an abstract method protected: it will be changed in a pubilc method. + """ + def baz(self): + """ + Baz gets a random boolean + Returns: + A random boolean value + """ + return bool(random.getrandbits(1)) + + @abstractmethod + def foo(self, foo) -> bool: + """ + Foo + Args: + foo(bool): a boolean value + Returns: + A boolean value + Raises: + NotImplementedError + """ + raise NotImplementedError From 42d976331fee778eac257f96b79ee2fd0a381e20 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 23:26:34 +0200 Subject: [PATCH 12/21] Update documentation --- docs/source/stepbystep.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/source/stepbystep.rst b/docs/source/stepbystep.rst index d63b356..65c898a 100644 --- a/docs/source/stepbystep.rst +++ b/docs/source/stepbystep.rst @@ -211,4 +211,35 @@ When you have created **tests/testMyClassAbstract.py** and added the new file, y Step 7 ****** +Now you can write your second class: see MyClassAbstract by `GitHub `_ or by command line with see-git-steps + +.. code-block:: bash + + $ cd python-prototype + $ see-git-steps -c ddb120bd0c14528b0c8b0caf223b387588725c50 -v + +When you have created **simple_sample/myClassAbstract.py**, you can run all unit tests like the command of step 5, or you can run only the unit tests of MyClassAbstract + +.. code-block:: bash + + $ cd python-prototype + $ python3 -m unittest -v tests/testMyClassAbstract.py + test_my_class_abstract_can_be_created (tests.testMyClassAbstract.TestMyClassAbstract) ... ok + + ---------------------------------------------------------------------- + Ran 1 test in 0.000s + + OK + +If the test is OK, you can add the new file and you can commit your changes + +.. code-block:: bash + + $ cd python-prototype + $ git add simple_sample/myClassAbstract.py + $ git commit -m "step 7 - add MyClassAbstract and unit tests works properly" + +Step 8 +****** + To be continued .. \ No newline at end of file From d78aacd6f3ef99d119b8ceb45d2378b1344d5f27 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 23:27:41 +0200 Subject: [PATCH 13/21] step 8 - add the unit test for MyClass --- tests/testMyClass.py | 75 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100755 tests/testMyClass.py diff --git a/tests/testMyClass.py b/tests/testMyClass.py new file mode 100755 index 0000000..1deb46d --- /dev/null +++ b/tests/testMyClass.py @@ -0,0 +1,75 @@ +"""Test class of MyClass + +This is a basic unit test class. There is a test for each public function. +If the functions contained conditions, there would be more tests for each public function. + +# license MIT +# author Alessandra Bilardi +# see https://github.com/bilardi/python-prototype for details +""" + +import unittest +from simple_sample.myClass import MyClass + +class TestMyClass(unittest.TestCase, MyClass): + """ + This is a basic unit test class. There is a test for each public function. + If the functions contained conditions, there would be more tests for each public function. + """ + # mc(MyClass): a class variable with default None + mc = None + def __init__(self, *args, **kwargs): + """ + Initialization of variables + """ + self.mc = MyClass() + unittest.TestCase.__init__(self, *args, **kwargs) + + def test_my_class_can_be_created(self): + """ + Verifies if the class MyClass can be created + """ + self.assertTrue(isinstance(self.mc, MyClass)) + + def test_my_class_gets_bar_value(self): + """ + Verifies if the class MyClass gets the bar value correctly + """ + self.assertTrue(self.mc.bar()) + + mc = MyClass(True) + self.assertTrue(mc.bar()) + + mc = MyClass(False) + self.assertFalse(mc.bar()) + + def test_my_class_gets_baz_value(self): + """ + Verifies if the class MyClass gets the baz value correctly + """ + for _ in range(10): + self.assertTrue(self.mc.baz() in [True, False]) + + def test_my_class_gets_foo_value(self): + """ + Verifies if the class MyClass gets the foo value correctly + """ + self.assertFalse(self.mc.foo(True)) + self.assertTrue(self.mc.foo(False)) + + def test_my_class_gets_qux_value(self): + """ + Verifies if the class MyClass qux method raises an exception + """ + with self.assertRaises(NotImplementedError): + self.mc.qux() + + def test_my_class_gets_fooquux_value(self): + """ + Verifies if the class MyClass gets the fooquux value correctly + """ + for _ in range(10): + self.assertTrue(self.mc.fooquux() in [True, False]) + +if __name__ == '__main__': + unittest.main() From 6ba6dc7c4407c4d92aa1ced571d3740ab9ed0c38 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 23:35:50 +0200 Subject: [PATCH 14/21] Update documentation --- docs/source/stepbystep.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/source/stepbystep.rst b/docs/source/stepbystep.rst index 65c898a..dce30b9 100644 --- a/docs/source/stepbystep.rst +++ b/docs/source/stepbystep.rst @@ -242,4 +242,23 @@ If the test is OK, you can add the new file and you can commit your changes Step 8 ****** +Now you can write the unit tests for a class can extend the interface class and the abstract class: note that it has been also added a unit test for the public method of the abstract class. +See the unit tests of MyClass by `GitHub `_ or by command line with see-git-steps + +.. code-block:: bash + + $ cd python-prototype + $ see-git-steps -c d78aacd6f3ef99d119b8ceb45d2378b1344d5f27 -v + +When you have created **tests/testMyClass.py** and added the new file, you can commit your changes + +.. code-block:: bash + + $ cd python-prototype + $ git add tests/testMyClass.py + $ git commit -m "step 6 - add the unit test for MyClass" + +Step 9 +****** + To be continued .. \ No newline at end of file From 84ce869d3ea3c5737d99b7b596be3fe4b3d826a4 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 23:36:18 +0200 Subject: [PATCH 15/21] step 9 - add MyClass and unit tests works properly --- simple_sample/myClass.py | 92 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100755 simple_sample/myClass.py diff --git a/simple_sample/myClass.py b/simple_sample/myClass.py new file mode 100755 index 0000000..ccafd9d --- /dev/null +++ b/simple_sample/myClass.py @@ -0,0 +1,92 @@ +"""An example of class + +An example of class that it extends an abstract class and it implements an interface. +There is a boolean pun by foo function of abstract class, bar function of interface class, +and foobar function of this class. + +# license MIT +# author Alessandra Bilardi +# see https://github.com/bilardi/python-prototype for details + +Note that the _quux method is not present in the documentation like the other methods because it is a method protected. + + >>> from simple_sample.myClass import MyClass + >>> help(MyClass) + +# cite https://stackoverflow.com/questions/11483366/protected-method-in-python/11483397#11483397 + +Python does not support access protection as C++/Java/C# does. Everything is public. +The motto is, "We're all adults here." Document your classes, and insist that your collaborators read and follow the documentation. +The culture in Python is that names starting with underscores mean, +"don't use these unless you really know you should." You might choose to begin your "protected" methods with underscores. +But keep in mind, this is just a convention, it doesn't change how the method can be accessed. +""" + +from simple_sample.myClassInterface import MyClassInterface +from simple_sample.myClassAbstract import MyClassAbstract + +class MyClass(MyClassInterface, MyClassAbstract): + """ + An example of class that it extends an abstract class and it implements an interface. + There is a boolean pun by foo function of abstract class, bar function of interface class, + and foobar function of this class. + Args: + bar(bool): a boolean value + """ + # bar(bool): a class boolean variable with default True + _bar = True + + def __init__(self, bar = True): + """ + Initialization of variables + Args: + bar(bool): a boolean value + """ + self._bar = bar + + def foo(self, foo): + """ + Foo gets reverse value of foo + Args: + foo(bool): a boolean value + Returns: + The reverse value of foo + """ + return not foo + + def bar(self): + """ + Bar + Returns: + The boolean value of _bar + """ + return self._bar + + def foobar(self): + """ + Foobar gets reverse value of _bar + Returns: + The reverse value of _bar + """ + return self.foo(self._bar) + + def _quux(self): + """ + Quux recalls some methods + Returns: + The boolean value + """ + try: + if MyClassInterface.bar(self) is None: + MyClassInterface.qux(self) + except NotImplementedError: + return self.baz() + return True + + def fooquux(self): + """ + Fooquux gets reverse value of protected method _quux + Returns: + The boolean value + """ + return self.foo(self._quux()) From d4e42fd657db394ad052f24675706800b47f652c Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 23:42:50 +0200 Subject: [PATCH 16/21] Update documentation --- docs/source/stepbystep.rst | 42 +++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/docs/source/stepbystep.rst b/docs/source/stepbystep.rst index dce30b9..d889bc7 100644 --- a/docs/source/stepbystep.rst +++ b/docs/source/stepbystep.rst @@ -256,9 +256,49 @@ When you have created **tests/testMyClass.py** and added the new file, you can c $ cd python-prototype $ git add tests/testMyClass.py - $ git commit -m "step 6 - add the unit test for MyClass" + $ git commit -m "step 8 - add the unit test for MyClass" Step 9 ****** +After verbalizing all MyClass methods by the unit tests, you are ready to write the methods: see MyClass by `GitHub `_ or by command line with see-git-steps + +.. code-block:: bash + + $ cd python-prototype + $ see-git-steps -c 84ce869d3ea3c5737d99b7b596be3fe4b3d826a4 -v + +When you have created **simple_sample/myClass.py**, you can run all unit tests + +.. code-block:: bash + + $ cd python-prototype + $ python3 -m unittest discover -v + test_my_class_can_be_created (tests.testMyClass.TestMyClass) ... ok + test_my_class_gets_bar_value (tests.testMyClass.TestMyClass) ... ok + test_my_class_gets_baz_value (tests.testMyClass.TestMyClass) ... ok + test_my_class_gets_foo_value (tests.testMyClass.TestMyClass) ... ok + test_my_class_gets_fooquux_value (tests.testMyClass.TestMyClass) ... ok + test_my_class_gets_qux_value (tests.testMyClass.TestMyClass) ... ok + test_my_class_abstract_can_be_created (tests.testMyClassAbstract.TestMyClassAbstract) ... ok + test_my_class_interface_can_be_created (tests.testMyClassInterface.TestMyClassInterface) ... ok + test_my_class_interface_gets_bar_value (tests.testMyClassInterface.TestMyClassInterface) ... ok + test_my_class_interface_gets_qux_value (tests.testMyClassInterface.TestMyClassInterface) ... ok + + ---------------------------------------------------------------------- + Ran 10 tests in 0.001s + + OK + +If all test is OK, you can add the new file and you can commit your changes + +.. code-block:: bash + + $ cd python-prototype + $ git add simple_sample/myClass.py + $ git commit -m "step 9 - add MyClass and unit tests works properly" + +Step 10 +****** + To be continued .. \ No newline at end of file From 999ce550c0b378011e94a76f654edf851c93ad52 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sat, 13 Jun 2020 23:48:53 +0200 Subject: [PATCH 17/21] step 10 - update changelog and version of the simple-sample package --- CHANGELOG.md | 10 +++++++++- docs/source/conf.py | 4 ++-- simple_sample/__init__.py | 2 +- 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ae69bb..ca2931f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.0.4] - 2020-06-14 + +### Added +- the interface class +- the abstract class +- a class that it extends an abstract class and it implements an interface + ## [0.0.1] - 2020-06-04 ### Added @@ -14,5 +21,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - the init files of package and tests - the documentation by sphinx -[Unreleased]: https://github.com/bilardi/python-prototype/compare/v0.0.1...HEAD +[Unreleased]: https://github.com/bilardi/python-prototype/compare/v0.0.4...HEAD +[0.0.4]: https://github.com/bilardi/python-prototype/releases/tag/v0.0.1...v0.0.4 [0.0.1]: https://github.com/bilardi/python-prototype/releases/tag/v0.0.1 diff --git a/docs/source/conf.py b/docs/source/conf.py index 6cf9e13..26775f9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -22,8 +22,8 @@ author = 'Alessandra Bilardi' # The full version, including alpha/beta/rc tags -version = '0.0.1' -release = '0.0.1' +version = '0.0.4' +release = '0.0.4' # specify the master doc, otherwise the build at read the docs fails master_doc = 'index' diff --git a/simple_sample/__init__.py b/simple_sample/__init__.py index e74429a..fa96bbd 100644 --- a/simple_sample/__init__.py +++ b/simple_sample/__init__.py @@ -13,5 +13,5 @@ # license MIT # support https://github.com/bilardi/python-prototype/issues """ -__version__ = '0.0.1' +__version__ = '0.0.4' __author__ = 'Alessandra Bilardi' From 4ee36b0b2392228480d209b0005caefac3e2bf17 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sun, 14 Jun 2020 00:00:05 +0200 Subject: [PATCH 18/21] Update documentation --- docs/source/stepbystep.rst | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/source/stepbystep.rst b/docs/source/stepbystep.rst index d889bc7..8364c21 100644 --- a/docs/source/stepbystep.rst +++ b/docs/source/stepbystep.rst @@ -127,7 +127,7 @@ So you can add CHANGELOG.md on your last commit, or you can create one commit fo $ cd python-prototype $ git add CHANGELOG.md $ git commit --amend # add file on your last commit - $ git tag -d v0.0.1 -m "Empty package and documentation by sphinx" # create a tag with that version name + $ git tag v0.0.1 -m "Empty package and documentation by sphinx" # create a tag with that version name $ git tag -n # show the tag list with description $ git push origin --tags # load the tag on repository @@ -301,4 +301,24 @@ If all test is OK, you can add the new file and you can commit your changes Step 10 ****** -To be continued .. \ No newline at end of file +You are completed the package, so you can tag that commit as a release. +This step could be run every time you complete a class with its unit test. +The files that you have to update are **CHANGELOG.md**, **docs/source/conf.py** and **simple_sample/__init__.py**, because they contain version number. +See the changes by `GitHub `_ or by command line with see-git-steps + +.. code-block:: bash + + $ cd python-prototype + $ see-git-steps -c 999ce550c0b378011e94a76f654edf851c93ad52 -v + +So you can add the files updated, you can create a commit dedicated, and then you can add the tag. + +.. code-block:: bash + + $ cd python-prototype + $ git add CHANGELOG.md docs/source/conf.py simple_sample/__init__.py + $ git commit -m "step 10 - update changelog and version of the simple-sample package" + $ git push origin master # load the commit on remote repository + $ git tag v0.0.4 -m "The first full version of the simple-sample package" # create a tag with that version name + $ git tag -n # show the tag list with description + $ git push origin --tags # load the tag on repository From 15c20f8c885edafc7ada09d52250c7074ebcc516 Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Thu, 31 Dec 2020 12:34:07 +0100 Subject: [PATCH 19/21] Update license's year --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index dfe641e..2419542 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2020 Alessandra Bilardi +Copyright (c) 2020-2021 Alessandra Bilardi Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal From 6195275ad2be2d09abcef049a2fc3f18497033ce Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Sun, 28 Mar 2021 20:04:46 +0200 Subject: [PATCH 20/21] Fixed some links and docs syntax --- README.rst | 6 +++--- docs/source/conf.py | 2 +- docs/source/stepbystep.rst | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index 2cc559c..203c543 100644 --- a/README.rst +++ b/README.rst @@ -28,7 +28,7 @@ Or you can install by python3-pip: Usage ##### -Read the unit tests in `tests/testMyClass.py `_ file to use it. This is a best practice. +Read the unit tests in `tests/testMyClass.py `_ file to use it. This is a best practice. You can read also the documentation by command line, .. code-block:: bash @@ -60,9 +60,9 @@ Test with unittest module Change Log ########## -See `CHANGELOG.md `_ for details. +See `CHANGELOG.md `_ for details. License ####### -This package is released under the MIT license. See `LICENSE `_ for details. +This package is released under the MIT license. See `LICENSE `_ for details. diff --git a/docs/source/conf.py b/docs/source/conf.py index 26775f9..c0eb1d8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,7 +18,7 @@ # -- Project information ----------------------------------------------------- project = 'simple-sample' -copyright = '2020, Alessandra Bilardi' +copyright = '2021, Alessandra Bilardi' author = 'Alessandra Bilardi' # The full version, including alpha/beta/rc tags diff --git a/docs/source/stepbystep.rst b/docs/source/stepbystep.rst index 8364c21..8b4df19 100644 --- a/docs/source/stepbystep.rst +++ b/docs/source/stepbystep.rst @@ -1,5 +1,5 @@ Step by step -============================ +============ This page is for learning all steps that they are necessary for writing a simple package like simple-sample. From f9efb123179acece7dfae03df26f12cf49f912fc Mon Sep 17 00:00:00 2001 From: Alessandra Bilardi Date: Tue, 22 Feb 2022 19:31:10 +0100 Subject: [PATCH 21/21] Update license's year --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index 2419542..3e55e37 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2020-2021 Alessandra Bilardi +Copyright (c) 2020-2022 Alessandra Bilardi Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal