8000 Monir Polishes · realpython/python-guide@148e650 · GitHub
[go: up one dir, main page]

Skip to content

Commit 148e650

Browse files
Monir Polishes
1 parent ad22d25 commit 148e650

File tree

2 files changed

+45
-46
lines changed

2 files changed

+45
-46
lines changed

docs/writing/structure.rst

Lines changed: 39 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -330,42 +330,42 @@ Easy structuring of a project means it is also easy
330330
to do it poorly. Some signs of a poorly structured project
331331
include:
332332

333-
- Multiple and messy circular dependencies: if your classes
333+
- Multiple and messy circular dependencies: If the classes
334334
Table and Chair in :file:`furn.py` need to import Carpenter from
335335
:file:`workers.py` to answer a question such as ``table.isdoneby()``,
336336
and if conversely the class Carpenter needs to import Table and Chair
337337
to answer the question ``carpenter.whatdo()``, then you
338338
have a circular dependency. In this case you will have to resort to
339-
fragile hacks such as using import statements inside
339+
fragile hacks such as using import statements inside your
340340
methods or functions.
341341

342-
- Hidden coupling: each and every change in Table's implementation
342+
- Hidden coupling: Each and every change in Table's implementation
343343
breaks 20 tests in unrelated test cases because it breaks Carpenter's code,
344-
which requires very careful surgery to adapt the change. This means
344+
which requires very careful surgery to adapt to the change. This means
345345
you have too many assumptions about Table in Carpenter's code or the
346346
reverse.
347347

348-
- Heavy usage of global state or context: instead of explicitly
348+
- Heavy usage of global state or context: Instead of explicitly
349349
passing ``(height, width, type, wood)`` to each other, Table
350350
and Carpenter rely on global variables that can be modified
351351
and are modified on the fly by different agents. You need to
352-
scrutinize all access to these global variables to understand why
352+
scrutinize all access to these global variables in order to understand why
353353
a rectangular table became a square, and discover that remote
354354
template code is also modifying this context, messing with
355-
table dimensions.
355+
the table dimensions.
356356

357357
- Spaghetti code: multiple pages of nested if clauses and for loops
358358
with a lot of copy-pasted procedural code and no
359359
proper segmentation are known as spaghetti code. Python's
360-
meaningful indentation (one of its most controversial features) make
361-
it very hard to maintain this kind of code. So the good news is that
360+
meaningful indentation (one of its most controversial features) makes
361+
it very hard to maintain this kind of code. The good news is that
362362
you might not see too much of it.
363363

364364
- Ravioli code is more likely in Python: it consists of hundreds of
365365
similar little pieces of logic, often classes or objects, without
366-
proper structure. If you never can remember if you have to use
366+
proper structure. If you never can remember, if you have to use
367367
FurnitureTable, AssetTable or Table, or even TableNew for your
368-
task at hand, you might be swimming in ravioli code.
368+
task at hand, then you might be swimming in ravioli code.
369369

370370

371371
*******
@@ -383,24 +383,24 @@ in one file, and all low-level operations in another file. In this case,
383383
the interface file needs to import the low-level file. This is done with the
384384
``import`` and ``from ... import`` statements.
385385

386-
As soon as you use `import` statements you use modules. These can be either
386+
As soon as you use `import` statements, you use modules. These can be either
387387
built-in modules such as `os` and `sys`, third-party modules you have installed
388388
in your environment, or your project's internal modules.
389389

390390
To keep in line with the style guide, keep module names short, lowercase, and
391391
be sure to avoid using special symbols like the dot (.) or question mark (?).
392-
So a file name like :file:`my.spam.py` is one you should avoid! Naming this way
392+
A file name like :file:`my.spam.py` is the one you should avoid! Naming this way
393393
will interfere with the way Python looks for modules.
394394

395395
In the case of `my.spam.py` Python expects to find a :file:`spam.py` file in a
396396
folder named :file:`my` which is not the case. There is an
397397
`example <http://docs.python.org/tutorial/modules.html#packages>`_ of how the
398398
dot notation should be used in the Python docs.
399399

400-
If you'd like you could name your module :file:`my_spam.py`, but even our
401-
friend the underscore should not be seen often in module names. However, using other
400+
If you like, you could name your module :file:`my_spam.py`, but even our trusty
401+
friend the underscore, should not be seen that often in module names. However, using other
402402
characters (spaces or hyphens) in module names will prevent importing
403-
(- is the subtract operator), so try to keep module names short so there is
403+
(- is the subtract operator). Try to keep module names short so there is
404404
no need to separate words. And, most of all, don't namespace with underscores; use submodules instead.
405405

406406
.. code-block:: python
@@ -411,15 +411,15 @@ no need to separate words. And, most of all, don't namespace with underscores; u
411411
import library.foo_plugin
412412
413413
Aside from some naming restrictions, nothing special is required for a Python
414-
file to be a module, but you need to understand the import mechanism in order
414+
file to be a module. But you need to understand the import mechanism in order
415415
to use this concept properly and avoid some issues.
416416

417417
Concretely, the ``import modu`` statement will look for the proper file, which
418-
is :file:`modu.py` in the same directory as the caller if it exists. If it is
418+
is :file:`modu.py` in the same directory as the caller, if it exists. If it is
419419
not found, the Python interpreter will search for :file:`modu.py` in the "path"
420-
recursively and raise an ImportError exception if it is not found.
420+
recursively and raise an ImportError exception when it is not found.
421421

422-
Once :file:`modu.py` is found, the Python interpreter will execute the module in
422+
When :file:`modu.py` is found, the Python interpreter will execute the module in
423423
an isolated scope. Any top-level statement in :file:`modu.py` will be executed,
424424
including other imports if any. Function and class definitions are stored in
425425
the module's dictionary.
@@ -436,7 +436,7 @@ unwanted effects, e.g. override an existing function with the same name.
436436

437437
It is possible to simulate the more standard behavior by using a special syntax
438438
of the import statement: ``from modu import *``. This is generally considered
439-
bad practice. **Using** ``import *`` **makes code harder to read and makes
439+
bad practice. **Using** ``import *`` **makes the code harder to read and makes
440440
dependencies less compartmentalized**.
441441

442442
Using ``from modu import func`` is a way to pinpoint the function you want to
@@ -492,20 +492,20 @@ modules, but with a special behavior for the :file:`__init__.py` file, which is
492492
used to gather all package-wide definitions.
493493

494494
A file :file:`modu.py` in the directory :file:`pack/` is imported with the
495-
statement ``import pack.modu``. This statement will look for an
495+
statement ``import pack.modu``. This statement will look for
496496
:file:`__init__.py` file in :file:`pack` and execute all of its top-level
497497
statements. Then it will look for a file named :file:`pack/modu.py` and
498498
execute all of its top-level statements. After these operations, any variable,
499499
function, or class defined in :file:`modu.py` is available in the pack.modu
500500
namespace.
501501

502-
A commonly seen issue is to add too much code to :file:`__init__.py`
502+
A commonly seen issue is adding too much code to :file:`__init__.py`
503503
files. When the project complexity grows, there may be sub-packages and
504504
sub-sub-packages in a deep directory structure. In this case, importing a
505505
single item from a sub-sub-package will require executing all
506506
:file:`__init__.py` files met while traversing the tree.
507507

508-
Leaving an :file:`__init__.py` file empty is considered normal and even a good
508+
Leaving an :file:`__init__.py` file empty is considered normal and even good
509509
practice, if the package's modules and sub-packages do not need to share any
510510
code.
511511

@@ -519,45 +519,44 @@ Object-oriented programming
519519
***************************
520520

521521
Python is sometimes described as an object-oriented programming language. This
522-
can be somewhat misleading and needs to be clarified.
522+
can be somewhat misleading and requires further clarifications.
523523

524524
In Python, everything is an object, and can be handled as such. This is what is
525525
meant when we say, for example, that functions are first-class objects.
526526
Functions, classes, strings, and even types are objects in Python: like any
527527
object, they have a type, they can be passed as function arguments, and they
528-
may have methods and properties. In this understanding, Python is an
529-
object-oriented language.
528+
may have methods and properties. In this understanding, Python can be considered
529+
as an object-oriented language.
530530

531531
However, unlike Java, Python does not impose object-oriented programming as the
532532
main programming paradigm. It is perfectly viable for a Python project to not
533533
be object-oriented, i.e. to use no or very few class definitions, class
534534
inheritance, or any other mechanisms that are specific to object-oriented
535-
programming.
535+
programming languages.
536536

537537
Moreover, as seen in the modules_ section, the way Python handles modules and
538538
namespaces gives the developer a natural way to ensure the
539539
encapsulation and separation of abstraction layers, both being the most common
540540
reasons to use object-orientation. Therefore, Python programmers have more
541-
latitude to not use object-orientation, when it is not required by the business
541+
latitude as to not use object-orientation, when it is not required by the business
542542
model.
543543

544544
There are some reasons to avoid unnecessary object-orientation. Defining
545-
custom classes is useful when we want to glue together some state and some
546-
functionality. The problem, as pointed out by the discussions about functional
545+
custom classes is useful when we want to glue some state and some
546+
functionality together. The problem, as pointed out by the discussions about functional
547547
programming, comes from the "state" part of the equation.
548548

549549
In some architectures, typically web applications, multiple instances of Python
550-
processes are spawned to respond to external requests that can happen at the
551-
same time. In this case, holding some state in instantiated objects, which
550+
processes are spawned as a response to external requests that happen simultaneously.
551+
In this case, holding some state in instantiated objects, which
552552
means keeping some static information about the world, is prone to concurrency
553553
problems or race conditions. Sometimes, between the initialization of the state
554554
of an object (usually done with the ``__init__()`` method) and the actual use
555555
of the object state through one of its methods, the world may have changed, and
556556
the retained state may be outdated. For example, a request may load an item in
557557
memory and mark it as read by a user. If another request requires the deletion
558-
of this item at the same time, it may happen that the deletion actually occurs
559-
after the first process loaded the item, and then we have to mark as read a
560-
deleted object.
558+
of this item at the same time, the deletion may actually occur after the first
559+
process loaded the item, and then we have to mark a deleted object as read.
561560

562561
This and other issues led to the idea that using stateless functions is a
563562
better programming paradigm.
@@ -571,7 +570,7 @@ or deletes data in a global variable or in the persistence layer, it is said to
571570
have a side-effect.
572571

573572
Carefully isolating functions with context and side-effects from functions with
574-
logic (called pure functions) allow the following benefits:
573+
logic (called pure functions) allows the following benefits:
575574

576575
- Pure functions are deterministic: given a fixed input,
577576
the output will always be the same.
@@ -713,7 +712,7 @@ type. In fact, in Python, variables are very different from what they are in
713712
many other languages, specifically statically-typed languages. Variables are not
714713
a segment of the computer's memory where some value is written, they are 'tags'
715714
or 'names' pointing to objects. It is therefore possible for the variable 'a' to
716-
be set to the value 1, then to the value 'a string', then to a function.
715+
be set to the value 1, then the value 'a string', to a function.
717716

718717
The dynamic typing of Python is often considered to be a weakness, and indeed
719718
it can lead to complexities and hard-to-debug code. Something named 'a' can be
@@ -743,7 +742,7 @@ Some guidelines help to avoid this issue:
743742
def func():
744743
pass # Do something
745744
746-
Using short functions or methods helps reduce the risk
745+
Using short functions or methods helps to reduce the risk
747746
of using the same name for two unrelated things.
748747

749748
It is better to use different names even for things that are related,
@@ -845,7 +844,7 @@ most idiomatic way to do this.
845844
846845
One final thing to mention about strings is that using ``join()`` is not always
847846
best. In the instances where you are creating a new string from a pre-determined
848-
number of strings, using the addition operator is actually faster, but in cases
847+
number of strings, using the addition operator is actually faster. But in cases
849848
like above or in cases where you are adding to an existing string, using
850849
``join()`` should be your preferred method.
851850

docs/writing/style.rst

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Code Style
88
.. image:: /_static/photos/33907150054_5ee79e8940_k_d.jpg
99

1010
If you ask Python programmers what they like most about Python, they will
11-
often cite its high readability. Indeed, a high level of readability
11+
often cite its high readability. Indeed, a high level of readability
1212
is at the heart of the design of the Python language, following the
1313
recognized fact that code is read much more often than it is written.
1414

@@ -644,7 +644,7 @@ provide a powerful, concise way to work with lists.
644644
`Generator expressions
645645
<http://docs.python.org/tutorial/classes.html#generator-expressions>`_
646646
follow almost the same syntax as list comprehensions but return a generator
647-
instead of a list.
647+
instead of a list.
648648

649649
Creating a new list requires more work and uses more memory. If you are just going
650650
to loop through the new list, prefer using an iterator instead.
@@ -668,7 +668,7 @@ example if you need to use the result multiple times.
668668

669669

670670
If your logic is too complicated for a short list comprehension or generator
671-
expression, consider using a generator function instead of returning a list.
671+
expression, consider using a generator function instead of returning a list.
672672

673673
**Good**:
674674

@@ -688,7 +688,7 @@ expression, consider using a generator function instead of returning a list.
688688
yield current_batch
689689
690690
691-
Never use a list comprehension just for its side effects.
691+
Never use a list comprehension just for its side effects.
692692

693693
**Bad**:
694694

@@ -701,7 +701,7 @@ Never use a list comprehension just for its side effects.
701701
.. code-block:: python
702702
703703
for x in sequence:
704-
print(x)
704+
print(x)
705705
706706
707707
Filtering a list
@@ -728,7 +728,7 @@ Don't make multiple passes through the list.
728728
729729
**Good**:
730730

731-
Use a list comprehension or generator expression.
731+
Use a list comprehension or generator expression.
732732

733733
.. code-block:: python
734734

0 commit comments

Comments
 (0)
0