8000 Update best practices · jerry-git/learn-python3@25a3752 · GitHub
[go: up one dir, main page]
Skip to content

Commit 25a3752

Browse files
jerry-gitjerry-git
committed
Update best practices
1 parent dbf5aaf commit 25a3752

File tree

2 files changed

+31
-180
lines changed

2 files changed

+31
-180
lines changed

‎notebooks/intermediate/html/01_best_practices.html

Lines changed: 14 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -15149,13 +15149,11 @@ <h3 id="Why">Why<a class="anchor-link" href="#Why">&#182;</a></h3><ul>
1514915149
</div>
1515015150
<div class="jp-InputArea jp-Cell-inputArea"><div class="jp-InputPrompt jp-InputArea-prompt">
1515115151
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
15152-
<h3 id="Tooling">Tooling<a class="anchor-link" href="#Tooling">&#182;</a></h3><p><code>pipenv</code> is currently the recommended tool for dependency management but <a href="https://packaging.python.org/guides/tool-recommendations/#application-dependency-management">&quot;consider other tools such as pip when pipenv does not meet your use case&quot;</a>. If <code>pipenv</code> doesn't fit your use case, I recommend using <code>virtualenvwrapper</code> for managing virtual environments and <code>pip</code> for package management. On the other hand, if you're working on only a couple of projects, built-in <a href="https://docs.python.org/3/library/venv.html"><code>venv</code></a> will do just fine.</p>
15153-
<h4 id="pipenv"><a href="https://pipenv.readthedocs.io/en/latest/"><code>pipenv</code></a><a class="anchor-link" href="#pipenv">&#182;</a></h4><ul>
15154-
<li>Basically combines <code>pip</code> and <code>virtualenv</code> under single CLI</li>
15155-
<li><a href="https://pipenv.readthedocs.io/en/latest/basics/#example-pipfile">Pipfile</a> which replaces the need for requirements.txt and requirements-dev.txt</li>
15156-
<li><a href="https://pipenv.readthedocs.io/en/latest/basics/#example-pipfile-lock">Pipfile.lock</a> which pins dependencies, this means deterministic builds</li>
15157-
<li>Possibility to visualize the <a href="https://pipenv.readthedocs.io/en/latest/#pipenv-graph">dependency graph</a></li>
15158-
<li><a href="https://pipenv.readthedocs.io/en/latest/advanced/#automatic-python-installation">Compatible with <code>pyenv</code></a></li>
15152+
<h3 id="Tooling">Tooling<a class="anchor-link" href="#Tooling">&#182;</a></h3><p><code>poetry</code> is currently the recommended tool for dependency management but <a href="https://packaging.python.org/guides/tool-recommendations/#application-dependency-management">&quot;consider other tools such as pip when poetry does not meet your use case&quot;</a>. If <code>poetry</code> doesn't fit your use case, I recommend using <code>virtualenvwrapper</code> for managing virtual environments and <code>pip</code> for package management. On the other hand, if you're working on only a couple of projects, built-in <a href="https://docs.python.org/3/library/venv.html"><code>venv</code></a> will do just fine.</p>
15153+
<h4 id="poetry"><a href="https://python-poetry.org/docs/"><code>poetry</code></a><a class="anchor-link" href="#poetry">&#182;</a></h4><ul>
15154+
<li>Basically combines <code>pip</code>, <code>virtualenv</code>, and packaging facilities under single CLI</li>
15155+
<li><a href="https://python-poetry.org/docs/pyproject/">pyproject.toml</a> which replaces the need for requirements.txt and requirements-dev.txt</li>
15156+
<li>poetry.lock which pins dependencies, this means deterministic builds</li>
1515915157
</ul>
1516015158

1516115159
</div>
@@ -15356,21 +15354,6 @@ <h3 id="Why">Why<a class="anchor-link" href="#Why">&#182;</a></h3><ul>
1535615354
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
1535715355
<h3 id="Tooling---code-formatters">Tooling - code formatters<a class="anchor-link" href="#Tooling---code-formatters">&#182;</a></h3><p><a href="https://www.python.org/dev/peps/pep-0008/?">PEP8</a> (see also <a href="https://pep8.org/">&quot;for humans version&quot;</a>) describes the style guidelines for Python code, you should follow them. Luckily, there are awesome tools that handle this for you while you focus on writing code, not formatting it.</p>
1535815356

15359-
</div>
15360-
</div>
15361-
</div>
15362-
</div>
15363-
<div class="jp-Cell jp-MarkdownCell jp-Notebook-cell">
15364-
<div class="jp-Cell-inputWrapper">
15365-
<div class="jp-Collapser jp-InputCollapser jp-Cell-inputCollapser">
15366-
</div>
15367-
<div class="jp-InputArea jp-Cell-inputArea"><div class="jp-InputPrompt jp-InputArea-prompt">
15368-
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
15369-
<h4 id="yapf"><a href="https://github.com/google/yapf"><code>yapf</code></a><a class="anchor-link" href="#yapf">&#182;</a></h4><ul>
15370-
<li><a href="https://www.python.org/dev/peps/pep-0008/?">PEP8</a> compliant code that also looks good</li>
15371-
<li>Loads of <a href="https://github.com/google/yapf#knobs">configuration options</a> - but also reasonable defaults</li>
15372-
</ul>
15373-
1537415357
</div>
1537515358
</div>
1537615359
</div>
@@ -15382,11 +15365,7 @@ <h4 id="yapf"><a href="https://github.com/google/yapf"><code>yapf</code></a><a c
1538215365
<div class="jp-InputArea jp-Cell-inputArea"><div class="jp-InputPrompt jp-InputArea-prompt">
1538315366
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
1538415367
<h4 id="black"><a href="https://black.readthedocs.io/en/stable/"><code>black</code></a><a class="anchor-link" href="#black">&#182;</a></h4><ul>
15385-
<li>Note requires Python 3.6+</li>
15386-
<li>Note &quot;This is a beta product&quot; while writing this</li>
15387-
<li>Uncompromising - not as many configuration options as in <code>yapf</code></li>
15388-
<li>Good <a href="https://black.readthedocs.io/en/stable/editor_integration.html">integration with editors</a></li>
15389-
<li>Try it in the <a href="https://black.now.sh">playground</a></li>
15368+
<li>This is the go-to formatter of the Python community</li>
1539015369
</ul>
1539115370

1539215371
</div>
@@ -15411,38 +15390,8 @@ <h3 id="Tooling---linters">Tooling - linters<a class="anchor-link" href="#Toolin
1541115390
</div>
1541215391
<div class="jp-InputArea jp-Cell-inputArea"><div class="jp-InputPrompt jp-InputArea-prompt">
1541315392
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
15414-
<h4 id="flake8"><a href="http://flake8.pycqa.org/en/latest/"><code>flake8</code></a><a class="anchor-link" href="#flake8">&#182;</a></h4><ul>
15415-
<li>Wraps <a href="https://pypi.org/project/mccabe/"><code>mccabe</code></a> (complexity checker), <a href="https://pypi.org/project/pycodestyle/"><code>pycodestyle</code></a> (PEP8), and <a href="https://pypi.org/project/pyflakes/"><code>pyflakes</code></a> (error checker)</li>
15416-
</ul>
15417-
15418-
</div>
15419-
</div>
15420-
</div>
15421-
</div>
15422-
<div class="jp-Cell jp-MarkdownCell jp-Notebook-cell">
15423-
<div class="jp-Cell-inputWrapper">
15424-
<div class="jp-Collapser jp-InputCollapser jp-Cell-inputCollapser">
15425-
</div>
15426-
<div class="jp-InputArea jp-Cell-inputArea"><div class="jp-InputPrompt jp-InputArea-prompt">
15427-
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
15428-
<h4 id="pylint"><a href="https://pylint.readthedocs.io/en/latest/"><code>pylint</code></a><a class="anchor-link" href="#pylint">&#182;</a></h4><ul>
15429-
<li>More verbose compared to <code>flake8</code></li>
15430-
<li>Criticized about the default configuration but is easily configurable</li>
15431-
<li>Gives an overall score</li>
15432-
</ul>
15433-
15434-
</div>
15435-
</div>
15436-
</div>
15437-
</div>
15438-
<div class="jp-Cell jp-MarkdownCell jp-Notebook-cell">
15439-
<div class="jp-Cell-inputWrapper">
15440-
<div class="jp-Collapser jp-InputCollapser jp-Cell-inputCollapser">
15441-
</div>
15442-
<div class="jp-InputArea jp-Cell-inputArea"><div class="jp-InputPrompt jp-InputArea-prompt">
15443-
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
15444-
<h4 id="bandit"><a href="https://pypi.org/project/bandit/"><code>bandit</code></a><a class="anchor-link" href="#bandit">&#182;</a></h4><ul>
15445-
<li>Checks for security vulnerabilities</li>
15393+
<h4 id="ruff"><a href="https://beta.ruff.rs/docs/"><code>ruff</code></a><a class="anchor-link" href="#ruff">&#182;</a></h4><ul>
15394+
<li>Most comprehensive linter. As a bonus, it's extremely fast.</li>
1544615395
</ul>
1544715396

1544815397
</div>
@@ -15611,10 +15560,9 @@ <h3 id="Why">Why<a class="anchor-link" href="#Why">&#182;</a></h3><ul>
1561115560
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
1561215561
<h3 id="Tooling">Tooling<a class="anchor-link" href="#Tooling">&#182;</a></h3><p>Tooling depends on which git repository manager option you've chosen and what kind of requirements you have. For example:</p>
1561315562
<ul>
15614-
<li>Gitlab has a built-in <a href="https://about.gitlab.com/features/gitlab-ci-cd/">integrated CI/CD</a></li>
15563+
<li><a href="https://github.com/features/actions">GitHub Actions</a></li>
15564+
<li>If you're using Gitlab, it also has <a href="https://about.gitlab.com/features/gitlab-ci-cd/">integrated CI/CD</a></li>
1561515565
<li>Same for <a href="https://www.atlassian.com/continuous-delivery/continuous-integration-tutorial">BitBucket</a></li>
15616-
<li>If you're using GitHub, see <a href="https://github.com/marketplace/category/continuous-integration">full list of available tools</a></li>
15617-
<li>There's an extensive comparison of different providers in <a href="https://en.wikipedia.org/wiki/Comparison_of_continuous_integration_software">wikipedia</a></li>
1561815566
</ul>
1561915567

1562015568
</div>
@@ -15785,9 +15733,8 @@ <h3 id="Tooling---profilers">Tooling - profilers<a class="anchor-link" href="#To
1578515733
</div>
1578615734
<div class="jp-InputArea jp-Cell-inputArea"><div class="jp-InputPrompt jp-InputArea-prompt">
1578715735
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
15788-
<h4 id="gprof2dot"><a href="https://github.com/jrfonseca/gprof2dot"><code>gprof2dot</code></a><a class="anchor-link" href="#gprof2dot">&#182;</a></h4><ul>
15789-
<li>Find the performance bottlenecks of your application via illustrative graphs</li>
15790-
<li>If you're using <code>pytest</code> (like you should), see also <a href="https://pypi.org/project/pytest-profiling/"><code>pytest-profiling</code></a> which is powered by <code>gprof2dot</code></li>
15736+
<h4 id="memray"><a href="https://bloomberg.github.io/memray/"><code>memray</code></a><a class="anchor-link" href="#memray">&#182;</a></h4><ul>
15737+
<li>Probably the only memory profiler you'll ever need</li>
1579115738
</ul>
1579215739

1579315740
</div>
@@ -15805,20 +15752,6 @@ <h4 id="py-spy"><a href="https://github.com/benfred/py-spy"><code>py-spy</code><
1580515752
<li>Potential tool for identifying problems of e.g. a web application in production</li>
1580615753
</ul>
1580715754

15808-
</div>
15809-
</div>
15810-
</div>
15811-
</div>
15812-
<div class="jp-Cell jp-MarkdownCell jp-Notebook-cell">
15813-
<div class="jp-Cell-inputWrapper">
15814-
<div class="jp-C F438 ollapser jp-InputCollapser jp-Cell-inputCollapser">
15815-
</div>
15816-
<div class="jp-InputArea jp-Cell-inputArea"><div class="jp-InputPrompt jp-InputArea-prompt">
15817-
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
15818-
<h4 id="objgraph"><a href="https://mg.pov.lt/objgraph/"><code>objgraph</code></a><a class="anchor-link" href="#objgraph">&#182;</a></h4><ul>
15819-
<li>Graphs which are useful while hunting memory leaks</li>
15820-
</ul>
15821-
1582215755
</div>
1582315756
</div>
1582415757
</div>
@@ -15847,32 +15780,6 @@ <h4 id="Sentry"><a href="https://docs.sentry.io/?platform=python">Sentry</a><a c
1584715780
<li>Support for other languages as well</li>
1584815781
</ul>
1584915782

15850-
</div>
15851-
</div>
15852-
</div>
15853-
</div>
15854-
<div class="jp-Cell jp-MarkdownCell jp-Notebook-cell">
15855-
<div class="jp-Cell-inputWrapper">
15856-
<div class="jp-Collapser jp-InputCollapser jp-Cell-inputCollapser">
15857-
</div>
15858-
<div class="jp-InputArea jp-Cell-inputArea"><div class="jp-InputPrompt jp-InputArea-prompt">
15859-
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
15860-
<h4 id="rollbar"><a href="https://docs.rollbar.com/docs/python"><code>rollbar</code></a><a class="anchor-link" href="#rollbar">&#182;</a></h4><ul>
15861-
<li>Very similar to sentry</li>
15862-
</ul>
15863-
15864-
</div>
15865-
</div>
15866-
</div>
15867-
</div>
15868-
<div class="jp-Cell jp-MarkdownCell jp-Notebook-cell">
15869-
<div class="jp-Cell-inputWrapper">
15870-
<div class="jp-Collapser jp-InputCollapser jp-Cell-inputCollapser">
15871-
</div>
15872-
<div class="jp-InputArea jp-Cell-inputArea"><div class="jp-InputPrompt jp-InputArea-prompt">
15873-
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
15874-
<p>While writing this, both sentry and rollbar are free for hobbyist use.</p>
15875-
1587615783
</div>
1587715784
</div>
1587815785
</div>
@@ -15924,7 +15831,8 @@ <h4 id="Use-logging-instead-of-prints">Use logging instead of prints<a class="an
1592415831
<div class="jp-InputArea jp-Cell-inputArea"><div class="jp-InputPrompt jp-InputArea-prompt">
1592515832
</div><div class="jp-RenderedHTMLCommon jp-RenderedMarkdown jp-MarkdownOutput " data-mime-type="text/markdown">
1592615833
<h3 id="General-guidelines">General guidelines<a class="anchor-link" href="#General-guidelines">&#182;</a></h3><ul>
15927-
<li>Use Python 3, legacy Python (aka 2.7) will <a href="https://pythonclock.org/">retire soon</a></li>
15834+
<li>If you're building applications, use the latest Python.</li>
15835+
<li>If you're building libraries, make sure they support also older Python versions.</li>
1592815836
<li>Develop in branches. Even if you're the only person in the project, branching makes it possible to easily switch between different features / bug fixes.</li>
1592915837
<li>If you're not developing alone, practice code reviews. It's one of the best ways to learn for both parties.</li>
1593015838
<li>Document your master pieces</li>

0 commit comments

Comments
 (0)
0