kennethreitz/python-guide
1
0
Fork 0
mirror of https://github.com/kennethreitz/python-guide.git synced 2026-06-05 23:00:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Host photos locally

Browse Source
This commit is contained in:
Dan Bader
2018-07-16 17:51:29 -07:00
parent 71e387ada6
commit 03ed5fbf0d
92 changed files with 168 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/writing/documentation.rst
+14 -14
View File
@@ -1,7 +1,7 @@
Documentation
=============
.. image:: https://farm5.staticflickr.com/4279/35620636012_f66aa88f93_k_d.jpg
.. image:: /_static/photos/35620636012_f66aa88f93_k_d.jpg
Readability is a primary focus for Python developers, in both project
and code documentation. Following some simple best practices can save
@@ -67,10 +67,10 @@ There is also **great**, **free** hosting for your Sphinx_ docs:
your source repository so that rebuilding your documentation will
happen automatically.
When run, Sphinx_ will import your code and using Python's introspection
When run, Sphinx_ will import your code and using Python's introspection
features it will extract all function, method and class signatures. It will
also extract the accompanying docstrings, and compile it all into well
structured and easily readable documentation for your project.
structured and easily readable documentation for your project.
.. note::
@@ -146,7 +146,7 @@ their source code, and as a side effect, it also ensures that their code is
tested and works.
::
def my_function(a, b):
"""
>>> my_function(2, 3)
@@ -175,14 +175,14 @@ comment block is a programmer's note. The docstring describes the
Unlike block comments, docstrings are built into the Python language itself.
This means you can use all of Python's powerful introspection capabilities to
access docstrings at runtime, compared with comments which are optimised out.
Docstrings are accessible from both the `__doc__` dunder attribute for almost
Docstrings are accessible from both the `__doc__` dunder attribute for almost
every Python object, as well as with the built in `help()` function.
While block comments are usually used to explain *what* a section of code is
doing, or the specifics of an algorithm, docstrings are more intended for
explaining to other users of your code (or you in 6 months time) *how* a
particular function can be used and the general purpose of a function, class,
or module.
particular function can be used and the general purpose of a function, class,
or module.
Writing Docstrings
~~~~~~~~~~~~~~~~~~
@@ -196,19 +196,19 @@ really obvious cases, such as::
return a + b
The docstring should describe the function in a way that is easy to understand.
For simple cases like trivial functions and classes, simply embedding the
function's signature (i.e. `add(a, b) -> result`) in the docstring is
unnecessary. This is because with Python's `inspect` module, it is already
For simple cases like trivial functions and classes, simply embedding the
function's signature (i.e. `add(a, b) -> result`) in the docstring is
unnecessary. This is because with Python's `inspect` module, it is already
quite easy to find this information if needed, and it is also readily available
by reading the source code.
by reading the source code.
In larger or more complex projects however, it is often a good idea to give
more information about a function, what it does, any exceptions it may raise,
In larger or more complex projects however, it is often a good idea to give
more information about a function, what it does, any exceptions it may raise,
what it returns, or relevant details about the parameters.
For more detailed documentation of code a popular style is the one used for the
Numpy project, often called `Numpy style`_ docstrings. While it can take up more
lines than the previous example, it allows the developer to include a lot
lines than the previous example, it allows the developer to include a lot
more information about a method, function, or class. ::
def random_number_generator(arg1, arg2):
docs/writing/gotchas.rst
+1 -1
View File
@@ -1,7 +1,7 @@
Common Gotchas
==============
.. image:: https://farm5.staticflickr.com/4163/34435688380_b5a740762b_k_d.jpg
.. image:: /_static/photos/34435688380_b5a740762b_k_d.jpg
For the most part, Python aims to be a clean and consistent language that
avoids surprises. However, there are a few cases that can be confusing to
docs/writing/license.rst
+1 -1
View File
@@ -1,7 +1,7 @@
Choosing a License
==================
.. image:: https://farm5.staticflickr.com/4228/33907149294_82d7535a6c_k_d.jpg
.. image:: /_static/photos/33907149294_82d7535a6c_k_d.jpg
Your source publication *needs* a license. In the US, if no license is
specified, users have no legal right to download, modify, or distribute.
docs/writing/logging.rst
+9 -9
View File
@@ -1,7 +1,7 @@
Logging
=======
.. image:: https://farm5.staticflickr.com/4246/35254379756_c9fe23f843_k_d.jpg
.. image:: /_static/photos/35254379756_c9fe23f843_k_d.jpg
The :mod:`logging` module has been a part of Python's Standard Library since
version 2.3. It is succinctly described in :pep:`282`. The documentation
@@ -37,14 +37,14 @@ Other reasons why logging is better than ``print``:
Logging in a Library
--------------------
Notes for `configuring logging for a library`_ are in the
Notes for `configuring logging for a library`_ are in the
`logging tutorial`_. Because the *user*, not the library, should
dictate what happens when a logging event occurs, one admonition bears
repeating:
.. note::
It is strongly advised that you do not add any handlers other than
NullHandler to your library’s loggers.
NullHandler to your library’s loggers.
Best practice when instantiating loggers in a library is to only create them
@@ -100,23 +100,23 @@ section of the `logging tutorial`_.
[loggers]
keys=root
[handlers]
keys=stream_handler
[formatters]
keys=formatter
[logger_root]
level=DEBUG
handlers=stream_handler
[handler_stream_handler]
class=StreamHandler
level=DEBUG
formatter=formatter
args=(sys.stderr,)
[formatter_formatter]
format=%(asctime)s %(name)-12s %(levelname)-8s %(message)s
@@ -131,7 +131,7 @@ Then use :meth:`logging.config.fileConfig` in the code:
fileConfig('logging_config.ini')
logger = logging.getLogger()
logger.debug('often makes a very good meal of %s', 'visiting tourists')
Example Configuration via a Dictionary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
docs/writing/reading.rst
+1 -1
View File
@@ -1,7 +1,7 @@
Reading Great Code
==================
.. image:: https://farm5.staticflickr.com/4221/34689452831_93d7fd0571_k_d.jpg
.. image:: /_static/photos/34689452831_93d7fd0571_k_d.jpg
One of the core tenets behind the design of Python is creating
readable code. The motivation behind this design is simple: The number
docs/writing/structure.rst
+7 -7
View File
@@ -1,7 +1,7 @@
Structuring Your Project
========================
.. image:: https://farm5.staticflickr.com/4203/33907151224_0574e7dfc2_k_d.jpg
.. image:: /_static/photos/33907151224_0574e7dfc2_k_d.jpg
By "structure" we mean the decisions you make concerning
how your project best meets its objective. We need to consider how to
@@ -395,9 +395,9 @@ folder named :file:`my` which is not the case. There is an
dot notation should be used in the Python docs.
If you'd like you could name your module :file:`my_spam.py`, but even our
friend the underscore should not be seen often in module names. However, using other
characters (spaces or hyphens) in module names will prevent importing
(- is the subtract operator), so try to keep module names short so there is
friend the underscore should not be seen often in module names. However, using other
characters (spaces or hyphens) in module names will prevent importing
(- is the subtract operator), so try to keep module names short so there is
no need to separate words. And, most of all, don't namespace with underscores, use submodules instead.
.. code-block:: python
@@ -799,7 +799,7 @@ its parts, it is much more efficient to accumulate the parts in a list,
which is mutable, and then glue ('join') the parts together when the
full string is needed. One thing to notice, however, is that list
comprehensions are better and faster than constructing a list in a loop
with calls to ``append()``.
with calls to ``append()``.
One other option is using the map function, which can 'map' a function
('str') to an iterable ('range(20)'). This results in a map object,
@@ -833,14 +833,14 @@ The map function can be even faster than a list comprehension in some cases.
# create a concatenated string from 0 to 19 (e.g. "012..1819")
nums = [str(n) for n in range(20)]
print "".join(nums)
**Best**
.. code-block:: python
# create a concatenated string from 0 to 19 (e.g. "012..1819")
nums = map(str, range(20))
print "".join(nums)
print "".join(nums)
One final thing to mention about strings is that using ``join()`` is not always
best. In the instances where you are creating a new string from a pre-determined
docs/writing/style.rst
+1 -1
View File
@@ -3,7 +3,7 @@
Code Style
==========
.. image:: https://farm5.staticflickr.com/4223/33907150054_5ee79e8940_k_d.jpg
.. image:: /_static/photos/33907150054_5ee79e8940_k_d.jpg
If you ask Python programmers what they like most about Python, they will
often cite its high readability. Indeed, a high level of readability
docs/writing/tests.rst
+7 -7
View File
@@ -1,11 +1,11 @@
Testing Your Code
=================
.. image:: https://farm5.staticflickr.com/4166/34435687940_8f73fc1fa6_k_d.jpg
.. image:: /_static/photos/34435687940_8f73fc1fa6_k_d.jpg
Testing your code is very important.
Getting used to writing testing code and running this code in parallel is now
Getting used to writing testing code and running this code in parallel is now
considered a good habit. Used wisely, this method helps you define more
precisely your code's intent and have a more decoupled architecture.
@@ -29,7 +29,7 @@ Some general rules of testing:
tests as often as needed.
- Learn your tools and learn how to run a single test or a test case. Then,
when developing a function inside a module, run this function's tests
when developing a function inside a module, run this function's tests
frequently, ideally automatically when you save the code.
- Always run the full test suite before a coding session, and run it again
@@ -65,10 +65,10 @@ Some general rules of testing:
- Another use of the testing code is as an introduction to new developers. When
someone will have to work on the code base, running and reading the related
testing code is often the best thing that they can do to start. They will
or should discover the hot spots, where most difficulties arise, and the
corner cases. If they have to add some functionality, the first step should
be to add a test to ensure that the new functionality is not already a
testing code is often the best thing that they can do to start. They will
or should discover the hot spots, where most difficulties arise, and the
corner cases. If they have to add some functionality, the first step should
be to add a test to ensure that the new functionality is not already a
working path that has not been plugged into the interface.
The Basics