# learn-python
[![CI][ci-badge]][ci-url]
[![CD][cd-badge]][cd-url]
[![PyPI version][pypi-badge]][pypi-url]
[![readthedocs build status][docs-badge]][docs-url]
[![License: Apache][apache-badge]][apache-url]
[![pre-commit][pre-commit-badge]][pre-commit-url]
[![Github pages][gh-pages-badge]][gh-pages-url]
[ci-url]: https://github.com/kagemeka/learn-python/actions/workflows/package-ci.yaml
[ci-badge]: https://github.com/kagemeka/learn-python/actions/workflows/package-ci.yaml/badge.svg
[cd-url]: https://github.com/kagemeka/learn-python/actions/workflows/package-cd.yaml
[cd-badge]: https://github.com/kagemeka/learn-python/actions/workflows/package-cd.yaml/badge.svg
[docs-badge]: https://readthedocs.org/projects/lpk/badge/?version=latest
[docs-url]: https://lpk.readthedocs.io
[pre-commit-badge]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=yellow
[pre-commit-url]: https://github.com/pre-commit/pre-commit
[apache-badge]: https://img.shields.io/badge/License-Apache2.0-brightgreen.svg
[apache-url]: https://opensource.org/licenses/Apache-2.0
[pypi-badge]: https://badge.fury.io/py/lpk.svg
[pypi-url]: https://badge.fury.io/py/lpk
[gh-pages-badge]: https://github.com/kagemeka/learn-python/actions/workflows/pages/pages-build-deployment/badge.svg
[gh-pages-url]: https://kagemeka.github.io/learn-python
## module
minimum unit of module is a python file. \
a directory containing python files is also a module. \
a single file module is a binary `__main__` when executed as `python3 <path/to/file>.py`, also is a library `__init__` when imported. \
a directory module can be a binary and executed as `python3 <path/to/directory>` by containing`__main__.py`, also can be a library and imported by containing`__init__.py`. \
python to `module/__init__.py` is as rust to `module/mod.rs`.
python to `module.py` is almost as rust to `module.rs` but also a binary.
top level `module/__main__.py` or `module.py` is as rust to `src/main.rs`
top level `module/__init__.py` or `module.py` is as rust to `src/lib.rs`
`__main__` and `__init__` are parts of meta info of a module.
there are a lot of other meta info. e.g. `__name__`
## package
package is also a module or collection of modules.
a package can be published to <https://pypi.org/>.
in actual, body of a package uploaded to the pypi registry is just a single module or some modules.
modules of a package are located under the project directly or the src directory by convention.
## poetry
<https://python-poetry.org/docs/>
the best package managing tool in Python project.
it was insipired by Rust's Cargo.
### manifest file
`pyproject.toml`
<https://python-poetry.org/docs/pyproject/>
### initialize a package
```sh
poetry init # current directory
poetry new <another> # create another package under current directory
```
### check virtual environments
```sh
poetry env info # check executable section and set this custom path when using vscode via `Python: select interpreter`.
poetry env list
```
### clear cache
```sh
poetry cache clear pypi --all
find . | grep -E "__pycache__$" | xargs rm -rf
```
### publish package
- <https://towardsdatascience.com/how-to-publish-a-python-package-to-pypi-using-poetry-aa804533fc6f>
- <https://www.digitalocean.com/community/tutorials/how-to-publish-python-packages-to-pypi-using-poetry-on-ubuntu-22-04>
make sure there is not same name package on <https://pypi.org>
```sh
poetry search <package>
```
currently you cannot publish with username and password.
you need to use api token.
```sh
poetry build
poetry publish -u=__token__ -p=<your pypi api token>
```
if it's redundant to input token every time.
```sh
poetry config pypi-token.pypi <your pypi api token>
```
and after that
```sh
poetry build
poetry publish
```
## process sources in a file only when executed as binary
```py
# processed whenever regardless of as library or binary.
...
if __name__ == __main__:
# processed only when executed as binary.
...
```
## testing
by convention, integration tests are located under top level tests directory.
and unittests are included in each module.
- frameworks
- unittest
- (std lib)
- <https://docs.python.org/3/library/unittest.html>
- doctest
- (std lib)
- <https://docs.python.org/3/library/doctest.html>
- pytest
- <https://docs.pytest.org/>
- <https://github.com/pytest-dev/pytest>
- <https://pypi.org/project/pytest/>
## documenting
- standard or third-party tools list summary
- <https://realpython.com/documenting-python-code/#documentation-tools-and-resources>
- <https://wiki.python.org/moin/DocumentationTools>
- hosting
- readthedocs
- <https://readthedocs.org/>
- <https://docs.readthedocs.io/en/stable/>
- github pages
- custom domain site of yours.
- generating/building
- sphinx
- <https://www.sphinx-doc.org/en/master/>
- <https://github.com/sphinx-doc/sphinx>
- <https://pypi.org/project/Sphinx/>
- functionality
- autodoc rst from codes
- build static htmls from rst
- publish
- usually automatically build & hosted from rst with readthedocs in CI/CD.
- you can also build html locally or in CI/CD & host on your own website.
```sh
# first, create conf.py and index.rst in <docs_source_path> like this package.
# then
./sphinx_build.sh
# open generated <docs_path>/sphinx_build/index.html
```
- mkdocs
- <https://www.mkdocs.org/>
- <https://pypi.org/project/mkdocs/>
- <https://github.com/mkdocs/mkdocs>
- functionality
- build static static htmls from markdowns
- cannot autodoc from codes.
- pdoc (easy, simple)
- <https://pypi.org/project/pdoc/>
- <https://github.com/mitmproxy/pdoc>
- <https://pdoc.dev/>
- functionality
- autodoc & build static htmls from codes
- publish
- you can also build html locally or in CI/CD pipelines, then host on your own website, github pages or other hosting services ...
- automate this processes with CI/CD like github actions.
```sh
./pdoc_build.sh
# open generated docs/with_pdoc/index.html
```
## linting
- <https://code.visualstudio.com/docs/python/linting>
- <https://code.visualstudio.com/docs/python/linting#_specific-linters>
- linter
- pylint
- <https://github.com/PyCQA/pylint>
- <https://www.pylint.org/>
- <https://docs.pylint.org/>
- <https://pypi.org/project/pylint/>
- flake8 (we recommend this)
- <https://flake8.pycqa.org/en/latest/>
- <https://pypi.org/project/flake8/>
- <https://github.com/PyCQA/flake8>
- mypy (we recommend)
- (typing linter)
- <https://mypy-lang.org/>
- <https://mypy.readthedocs.io/en/stable/>
- <https://github.com/python/mypy>
- <https://pypi.org/project/mypy/>
- pycodestyle
- (pep8 based)
- <https://pypi.org/project/pycodestyle/>
- <https://pycodestyle.pycqa.org/en/latest/>
- <https://github.com/PyCQA/pycodestyle>
- pydocstyle
- <http://www.pydocstyle.org/en/stable/>
- <https://pypi.org/project/pydocstyle/>
- <https://github.com/PyCQA/pydocstyle>
- prospector
- <https://prospector.landscape.io/en/master/>
- <https://pypi.org/project/prospector/>
- <https://github.com/PyCQA/prospector>
- pylama
- <https://klen.github.io/pylama/>
- <https://github.com/klen/pylama>
- <https://pypi.org/project/pylama/>
- bandit
- <https://bandit.readthedocs.io/en/latest/>
- <https://github.com/PyCQA/bandit>
- <https://pypi.org/project/bandit/>
## formatting
- formatter
- black (we recommend)
- <https://github.com/psf/black>
- <https://black.readthedocs.io/en/stable/>
- <https://pypi.org/project/black/>
- autopep8
- <https://pypi.org/project/autopep8/>
- <https://github.com/peter-evans/autopep8>
- isort (we recommend)
- sort imports
- <https://github.com/PyCQA/isort>
- <https://pycqa.github.io/isort/>
- <https://pypi.org/project/isort/>
## CI/CD & automation supporting
- frameworks
- tox
- <https://tox.wiki/en/latest/index.html>
- <https://pypi.org/project/tox/>
- <https://github.com/tox-dev/tox>
- nox
- <https://nox.thea.codes/en/stable/>
- <https://github.com/wntrblm/nox>
- <https://pypi.org/project/nox/>
- invoke
- <https://www.pyinvoke.org/>
- <https://github.com/pyinvoke/invoke/>
- <https://pypi.org/project/invoke/>
## Python public / private syntax convention
there is no private module and file private objects limited by syntax.
by convention, to convey that a module or object is private to users,
you can make it start with a single underscore `_`.
and objects private too.
on the other hand, class members can be public, protected, private
protected member start with a single underscore `_`.
private member start with two under scores `__`.
class to protected member is as a file to private object.
private member is completely different. cannot accessible from outside normally. to access it, `obj._ClassName__private_member`
also, private members are not inherited, so cannot be accessible anyhow through the childeren which inherited it.
## development with vscode
### extensions
- Python
- Pylance
- Live Server
- Even Better TOML
- Bash IDE
- autoDocstring - Python
- GitLens
- markdownlint
- YAML
- shell-format
Raw data
{
"_id": null,
"home_page": "https://github.com/kagemeka/learn-python#readme",
"name": "lpk",
"maintainer": "kagemeka",
"docs_url": null,
"requires_python": ">=3.10,<3.12",
"maintainer_email": "kagemeka1@gmail.com",
"keywords": "project,learning,packaging",
"author": "kagemeka",
"author_email": "kagemeka1@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/aa/0e/0d73c03c07e3d475ae334ff96968540bcbd1e661387452866c281e6cefea/lpk-0.2.0.tar.gz",
"platform": null,
"description": "# learn-python\n\n[![CI][ci-badge]][ci-url]\n[![CD][cd-badge]][cd-url]\n[![PyPI version][pypi-badge]][pypi-url]\n[![readthedocs build status][docs-badge]][docs-url]\n[![License: Apache][apache-badge]][apache-url]\n[![pre-commit][pre-commit-badge]][pre-commit-url]\n[![Github pages][gh-pages-badge]][gh-pages-url]\n\n[ci-url]: https://github.com/kagemeka/learn-python/actions/workflows/package-ci.yaml\n[ci-badge]: https://github.com/kagemeka/learn-python/actions/workflows/package-ci.yaml/badge.svg\n[cd-url]: https://github.com/kagemeka/learn-python/actions/workflows/package-cd.yaml\n[cd-badge]: https://github.com/kagemeka/learn-python/actions/workflows/package-cd.yaml/badge.svg\n[docs-badge]: https://readthedocs.org/projects/lpk/badge/?version=latest\n[docs-url]: https://lpk.readthedocs.io\n[pre-commit-badge]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=yellow\n[pre-commit-url]: https://github.com/pre-commit/pre-commit\n[apache-badge]: https://img.shields.io/badge/License-Apache2.0-brightgreen.svg\n[apache-url]: https://opensource.org/licenses/Apache-2.0\n[pypi-badge]: https://badge.fury.io/py/lpk.svg\n[pypi-url]: https://badge.fury.io/py/lpk\n[gh-pages-badge]: https://github.com/kagemeka/learn-python/actions/workflows/pages/pages-build-deployment/badge.svg\n[gh-pages-url]: https://kagemeka.github.io/learn-python\n\n## module\n\nminimum unit of module is a python file. \\\na directory containing python files is also a module. \\\na single file module is a binary `__main__` when executed as `python3 <path/to/file>.py`, also is a library `__init__` when imported. \\\na directory module can be a binary and executed as `python3 <path/to/directory>` by containing`__main__.py`, also can be a library and imported by containing`__init__.py`. \\\npython to `module/__init__.py` is as rust to `module/mod.rs`.\npython to `module.py` is almost as rust to `module.rs` but also a binary.\ntop level `module/__main__.py` or `module.py` is as rust to `src/main.rs`\ntop level `module/__init__.py` or `module.py` is as rust to `src/lib.rs`\n\n`__main__` and `__init__` are parts of meta info of a module.\nthere are a lot of other meta info. e.g. `__name__`\n\n## package\n\npackage is also a module or collection of modules.\na package can be published to <https://pypi.org/>.\nin actual, body of a package uploaded to the pypi registry is just a single module or some modules.\nmodules of a package are located under the project directly or the src directory by convention.\n\n## poetry\n\n<https://python-poetry.org/docs/>\n\nthe best package managing tool in Python project.\nit was insipired by Rust's Cargo.\n\n### manifest file\n\n`pyproject.toml`\n<https://python-poetry.org/docs/pyproject/>\n\n### initialize a package\n\n```sh\npoetry init # current directory\npoetry new <another> # create another package under current directory\n```\n\n### check virtual environments\n\n```sh\npoetry env info # check executable section and set this custom path when using vscode via `Python: select interpreter`.\npoetry env list\n```\n\n### clear cache\n\n```sh\npoetry cache clear pypi --all\nfind . | grep -E \"__pycache__$\" | xargs rm -rf\n```\n\n### publish package\n\n- <https://towardsdatascience.com/how-to-publish-a-python-package-to-pypi-using-poetry-aa804533fc6f>\n- <https://www.digitalocean.com/community/tutorials/how-to-publish-python-packages-to-pypi-using-poetry-on-ubuntu-22-04>\n\nmake sure there is not same name package on <https://pypi.org>\n\n```sh\npoetry search <package>\n```\n\ncurrently you cannot publish with username and password.\nyou need to use api token.\n\n```sh\npoetry build\npoetry publish -u=__token__ -p=<your pypi api token>\n```\n\nif it's redundant to input token every time.\n\n```sh\npoetry config pypi-token.pypi <your pypi api token>\n```\n\nand after that\n\n```sh\npoetry build\npoetry publish\n```\n\n## process sources in a file only when executed as binary\n\n```py\n# processed whenever regardless of as library or binary.\n...\n\n\nif __name__ == __main__:\n # processed only when executed as binary.\n ...\n```\n\n## testing\n\nby convention, integration tests are located under top level tests directory.\nand unittests are included in each module.\n\n- frameworks\n - unittest\n - (std lib)\n - <https://docs.python.org/3/library/unittest.html>\n - doctest\n - (std lib)\n - <https://docs.python.org/3/library/doctest.html>\n - pytest\n - <https://docs.pytest.org/>\n - <https://github.com/pytest-dev/pytest>\n - <https://pypi.org/project/pytest/>\n\n## documenting\n\n- standard or third-party tools list summary\n - <https://realpython.com/documenting-python-code/#documentation-tools-and-resources>\n - <https://wiki.python.org/moin/DocumentationTools>\n\n- hosting\n - readthedocs\n - <https://readthedocs.org/>\n - <https://docs.readthedocs.io/en/stable/>\n - github pages\n - custom domain site of yours.\n- generating/building\n - sphinx\n - <https://www.sphinx-doc.org/en/master/>\n - <https://github.com/sphinx-doc/sphinx>\n - <https://pypi.org/project/Sphinx/>\n - functionality\n - autodoc rst from codes\n - build static htmls from rst\n - publish\n - usually automatically build & hosted from rst with readthedocs in CI/CD.\n - you can also build html locally or in CI/CD & host on your own website.\n\n ```sh\n # first, create conf.py and index.rst in <docs_source_path> like this package.\n # then\n ./sphinx_build.sh\n # open generated <docs_path>/sphinx_build/index.html\n ```\n\n - mkdocs\n - <https://www.mkdocs.org/>\n - <https://pypi.org/project/mkdocs/>\n - <https://github.com/mkdocs/mkdocs>\n - functionality\n - build static static htmls from markdowns\n - cannot autodoc from codes.\n - pdoc (easy, simple)\n - <https://pypi.org/project/pdoc/>\n - <https://github.com/mitmproxy/pdoc>\n - <https://pdoc.dev/>\n - functionality\n - autodoc & build static htmls from codes\n - publish\n - you can also build html locally or in CI/CD pipelines, then host on your own website, github pages or other hosting services ...\n - automate this processes with CI/CD like github actions.\n\n ```sh\n ./pdoc_build.sh\n # open generated docs/with_pdoc/index.html\n ```\n\n## linting\n\n- <https://code.visualstudio.com/docs/python/linting>\n- <https://code.visualstudio.com/docs/python/linting#_specific-linters>\n- linter\n - pylint\n - <https://github.com/PyCQA/pylint>\n - <https://www.pylint.org/>\n - <https://docs.pylint.org/>\n - <https://pypi.org/project/pylint/>\n - flake8 (we recommend this)\n - <https://flake8.pycqa.org/en/latest/>\n - <https://pypi.org/project/flake8/>\n - <https://github.com/PyCQA/flake8>\n - mypy (we recommend)\n - (typing linter)\n - <https://mypy-lang.org/>\n - <https://mypy.readthedocs.io/en/stable/>\n - <https://github.com/python/mypy>\n - <https://pypi.org/project/mypy/>\n - pycodestyle\n - (pep8 based)\n - <https://pypi.org/project/pycodestyle/>\n - <https://pycodestyle.pycqa.org/en/latest/>\n - <https://github.com/PyCQA/pycodestyle>\n - pydocstyle\n - <http://www.pydocstyle.org/en/stable/>\n - <https://pypi.org/project/pydocstyle/>\n - <https://github.com/PyCQA/pydocstyle>\n - prospector\n - <https://prospector.landscape.io/en/master/>\n - <https://pypi.org/project/prospector/>\n - <https://github.com/PyCQA/prospector>\n - pylama\n - <https://klen.github.io/pylama/>\n - <https://github.com/klen/pylama>\n - <https://pypi.org/project/pylama/>\n - bandit\n - <https://bandit.readthedocs.io/en/latest/>\n - <https://github.com/PyCQA/bandit>\n - <https://pypi.org/project/bandit/>\n\n## formatting\n\n- formatter\n - black (we recommend)\n - <https://github.com/psf/black>\n - <https://black.readthedocs.io/en/stable/>\n - <https://pypi.org/project/black/>\n - autopep8\n - <https://pypi.org/project/autopep8/>\n - <https://github.com/peter-evans/autopep8>\n - isort (we recommend)\n - sort imports\n - <https://github.com/PyCQA/isort>\n - <https://pycqa.github.io/isort/>\n - <https://pypi.org/project/isort/>\n\n## CI/CD & automation supporting\n\n- frameworks\n - tox\n - <https://tox.wiki/en/latest/index.html>\n - <https://pypi.org/project/tox/>\n - <https://github.com/tox-dev/tox>\n - nox\n - <https://nox.thea.codes/en/stable/>\n - <https://github.com/wntrblm/nox>\n - <https://pypi.org/project/nox/>\n - invoke\n - <https://www.pyinvoke.org/>\n - <https://github.com/pyinvoke/invoke/>\n - <https://pypi.org/project/invoke/>\n\n## Python public / private syntax convention\n\nthere is no private module and file private objects limited by syntax.\nby convention, to convey that a module or object is private to users,\nyou can make it start with a single underscore `_`.\nand objects private too.\non the other hand, class members can be public, protected, private\nprotected member start with a single underscore `_`.\nprivate member start with two under scores `__`.\nclass to protected member is as a file to private object.\nprivate member is completely different. cannot accessible from outside normally. to access it, `obj._ClassName__private_member`\nalso, private members are not inherited, so cannot be accessible anyhow through the childeren which inherited it.\n\n## development with vscode\n\n### extensions\n\n- Python\n- Pylance\n- Live Server\n- Even Better TOML\n- Bash IDE\n- autoDocstring - Python\n- GitLens\n- markdownlint\n- YAML\n- shell-format\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "learning python",
"version": "0.2.0",
"split_keywords": [
"project",
"learning",
"packaging"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3bcafaf4cd09f46a434769b4126394876d79b6a53c7347089e9a693b81d9ab8d",
"md5": "1130c497aeb8820871ca22dbc6d86858",
"sha256": "e9cd9398b137660f74bd03b37861a588c69c050f61ca930bc14b6193f3cfc706"
},
"downloads": -1,
"filename": "lpk-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1130c497aeb8820871ca22dbc6d86858",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<3.12",
"size": 16157,
"upload_time": "2023-02-07T00:27:10",
"upload_time_iso_8601": "2023-02-07T00:27:10.907952Z",
"url": "https://files.pythonhosted.org/packages/3b/ca/faf4cd09f46a434769b4126394876d79b6a53c7347089e9a693b81d9ab8d/lpk-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aa0e0d73c03c07e3d475ae334ff96968540bcbd1e661387452866c281e6cefea",
"md5": "68ecc7cde2daa4b2bda6da1b857b1487",
"sha256": "be8e1dd90e2f746bb1ef6c6dbfdc141a8859982ec7443180473f6f912f3ab16d"
},
"downloads": -1,
"filename": "lpk-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "68ecc7cde2daa4b2bda6da1b857b1487",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<3.12",
"size": 16235,
"upload_time": "2023-02-07T00:27:12",
"upload_time_iso_8601": "2023-02-07T00:27:12.421090Z",
"url": "https://files.pythonhosted.org/packages/aa/0e/0d73c03c07e3d475ae334ff96968540bcbd1e661387452866c281e6cefea/lpk-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-07 00:27:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "kagemeka",
"github_project": "learn-python#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "lpk"
}
JSON
