book

Pro Python

Name: Pro Python
Author: Marty Alchin
ISBN: 9781430227571

by Marty Alchin

June 2010

Beginner

361 pages

10h 2m

English

Apress

Read now

Unlock full access

Copyright
About the Author
About the Technical Reviewer
Acknowledgments
Introduction
Who This Book Is ForWhat You'll NeedSource Code
1. Principles and Philosophy
1.1. The Zen of Python1.1.1. Beautiful Is Better Than Ugly1.1.2. Explicit Is Better Than Implicit1.1.3. Simple Is Better Than Complex1.1.4. Complex Is Better Than Complicated1.1.5. Flat Is Better Than Nested1.1.6. Sparse Is Better Than Dense1.1.7. Readability Counts1.1.8. Special Cases Aren't Special Enough to Break the Rules1.1.9. Although Practicality Beats Purity1.1.10. Errors Should Never Pass Silently1.1.11. Unless Explicitly Silenced1.1.12. In the Face of Ambiguity, Refuse the Temptation to Guess1.1.13. There Should Be One—and Preferably Only One— Obvious Way to Do It1.1.14. Although That Way May Not Be Obvious at First Unless You're Dutch1.1.15. Now Is Better Than Never1.1.16. Although Never Is Often Better Than Right Now1.1.17. If the Implementation is Hard to Explain, It's a Bad Idea1.1.18. If the Implementation is Easy to Explain, It May Be a Good Idea1.1.19. Namespaces Are One Honking Great Idea— Let's Do More of Those!1.2. Don't Repeat Yourself1.3. Loose Coupling1.4. The Samurai Principle1.5. The Pareto Principle1.6. The Robustness Principle1.7. Backward Compatibility1.8. The Road to Python 3.01.9. Taking It With You
2. Advanced Basics
2.1. General Concepts2.1.1. Iteration2.1.2. Caching2.1.3. Transparency2.2. Control Flow2.2.1. Catching Exceptions2.2.2. Exception Chains2.2.3. When Everything Goes Right2.2.4. Proceeding Regardless of Exceptions2.2.5. Optimizing Loops2.2.6. The with Statement2.2.7. Conditional Expressions2.3. Iteration2.3.1. Sequence Unpacking2.3.2. List Comprehensions2.3.3. Generator Expressions2.3.4. Set Comprehensions2.3.5. Dictionary Comprehensions2.3.6. Chaining Iterables Together2.3.7. Zipping Iterables Together2.4. Collections2.4.1. Sets2.4.2. Named Tuples2.4.3. Ordered Dictionaries2.4.4. Dictionaries with Defaults2.5. Importing Code2.5.1. Fallback Imports2.5.2. Importing from the Future2.5.3. Using __all__ to Customize Imports2.5.4. Relative Imports2.5.5. The __import__() function2.5.6. The importlib module2.6. Taking It With You
3. Functions
3.1. Arguments3.1.1. Planning for Flexibility3.1.2. Variable Positional Arguments3.1.3. Variable Keyword Arguments3.1.4. Combining Different Kinds of Arguments3.1.5. Invoking Functions with Variable Arguments3.1.6. Preloading Arguments3.1.7. Introspection3.1.8. Example: Identifying Argument Values3.1.9. Example: A More Concise Version3.1.10. Example: Validating Arguments3.2. Decorators3.2.1. Closures3.2.2. Wrappers3.2.3. Decorators with Arguments3.2.4. Decorators with—or without—Arguments3.2.5. Example: Memoization3.2.6. Example: A Decorator to Create Decorators3.3. Function Annotations3.3.1. Example: Type Safety3.3.2. Factoring Out the Boilerplate3.3.3. Example: Type Coercion3.3.4. Annotating with Decorators3.3.5. Example: Type Safety as a Decorator3.4. Generators3.5. Lambdas3.6. Introspection3.6.1. Identifying Object Types3.6.2. Modules and Packages3.6.3. Docstrings3.7. Taking It With You
4. Classes
4.1. Inheritance4.1.1. Multiple Inheritance4.1.2. Method Resolution Order (MRO)4.1.3. Example: C3 Algorithm4.1.4. Using super() to Pass Control to Other Classes4.1.5. Introspection4.2. How Classes Are Created4.2.1. Creating Classes at Runtime4.2.2. Metaclasses4.2.3. Example: Plugin Framework4.2.4. Controlling the Namespace4.3. Attributes4.3.1. Properties4.3.2. Descriptors4.4. Methods4.4.1. Unbound Methods4.4.2. Bound Methods4.4.3. Class Methods4.4.4. Static Methods4.4.5. Assigning Functions to Classes and Instances4.5. Magic Methods4.5.1. Creating Instances4.5.2. Example: Automatic Subclasses4.5.3. Dealing with Attributes4.5.4. String Representations4.6. Taking It With You
5. Common Protocols
5.1. Basic Operations5.1.1. Mathematical Operations5.1.2. Bitwise Operations5.1.3. Variations5.2. Numbers5.2.1. Sign Operations5.2.2. Comparison Operations5.3. Iterables5.3.1. Example: Repeatable Generators5.4. Sequences5.5. Mappings5.6. Callables5.7. Context Managers5.8. Taking It With You

6. Object Management
6.1. Namespace Dictionary6.1.1. Example: Borg Pattern6.1.2. Example: Self-caching properties6.2. Garbage Collection6.2.1. Reference Counting6.2.2. Cyclical References6.2.3. Weak References6.3. Pickling6.4. Copying6.4.1. Shallow Copies6.4.2. Deep Copies6.5. Taking It With You
7. Strings
7.1. Bytes7.1.1. Simple Conversion: chr() and ord()7.1.2. Complex Conversion: The Struct Module7.2. Text7.2.1. Unicode7.2.2. Encodings7.3. Simple Substitution7.4. Formatting7.4.1. Looking Up Values Within Objects7.4.2. Distinguishing Types of Strings7.4.3. Standard Format Specification7.4.4. Example: Plain Text Table of Contents7.4.5. Custom Format Specification7.5. Taking It With You
8. Documentation
8.1. Proper Naming8.2. Comments8.3. Docstrings8.3.1. Describe What the Function Does8.3.2. Explain the Arguments8.3.3. Don't Forget the Return Value8.3.4. Include Any Expected Exceptions8.4. Documentation Outside the Code8.4.1. Installation and Configuration8.4.2. Tutorials8.4.3. Reference Documents8.5. Documentation Utilities8.5.1. Formatting8.5.2. Links8.5.3. Sphinx8.6. Taking It With You
9. Testing
9.1. Test-Driven Development (TDD)9.2. Doctests9.2.1. Formatting Code9.2.2. Representing Output9.2.3. Integrating With Documentation9.2.4. Running Tests9.3. The unittest module9.3.1. Setting Up9.3.2. Writing Tests9.3.3. Other Comparisons9.3.4. Testing Strings and Other Sequence Content9.3.5. Testing Exceptions9.3.6. Testing Identity9.3.7. Tearing Down9.4. Providing a Custom Test Class9.4.1. Changing Test Behavior9.5. Taking It With You
10. Distribution
10.1. Licensing10.1.1. GNU General Public License (GPL)10.1.2. Affero General Public License (AGPL)10.1.3. GNU Lesser General Public License (LGPL)10.1.4. Berkeley Software Distribution (BSD) License10.1.5. Other Licenses10.2. Packaging10.2.1. setup.py10.2.2. MANIFEST.in10.2.3. The sdist command10.3. Distribution10.4. Taking It With You
11. Sheets: A CSV Framework
11.1. Building a Declarative Framework11.1.1. Introducing Declarative Programming11.1.2. To Build or Not to Build?11.2. Building the Framework11.2.1. Managing Options11.2.2. Defining Fields11.2.3. Attaching a Field to a Class11.2.4. Adding a Metaclass11.2.5. Bringing It Together11.3. Ordering Fields11.3.1. DeclarativeMeta.__prepare__()11.3.2. Column.__init__()11.3.3. Column.__new__()11.3.4. CounterMeta.__call__()11.3.5. Choosing an Option11.4. Building a Field Library11.4.1. StringField11.4.2. IntegerColumn11.4.3. FloatColumn11.4.4. DecimalColumn11.4.5. DateColumn11.5. Getting Back to CSV11.5.1. Checking Arguments11.5.2. Populating Values11.5.3. The Reader11.5.4. The Writer11.6. Taking It With You
A. PEP 8: Style Guide for Python
A.1. IntroductionA.2. A Foolish Consistency is the Hobgoblin of Little MindsA.3. Code LayoutA.3.1. IndentationA.3.2. Tabs or Spaces?A.3.3. Maximum Line LengthA.3.4. Blank LinesA.3.5. Encodings (PEP 263)A.4. ImportsA.5. Whitespace in Expressions and StatementsA.5.1. Pet PeevesA.5.2. Other RecommendationsA.6. CommentsA.6.1. Block CommentsA.6.2. Inline CommentsA.7. Documentation StringsA.8. Version BookkeepingA.9. Naming ConventionsA.9.1. Descriptive: Naming StylesA.9.2. Prescriptive: Naming ConventionsA.9.2.1. Names to AvoidA.9.2.2. Package and Module NamesA.9.2.3. Class NamesA.9.2.4. Exception NamesA.9.2.5. Global Variable NamesA.9.2.6. Function NamesA.9.2.7. Function and Method ArgumentsA.9.2.8. Method Names and Instance VariablesA.9.2.9. ConstantsA.9.2.10. Designing for InheritanceA.10. Programming RecommendationsA.11. Copyright
B. PEP 10: Voting Guidelines
B.1. AbstractB.2. RationaleB.3. Voting ScoresB.4. Copyright
C. PEP 20: The Zen of Python
C.1. AbstractC.2. The Zen of PythonC.3. Easter EggC.4. Copyright
D. PEP 257: Docstring Conventions
D.1. AbstractD.2. RationaleD.3. SpecificationD.3.1. What is a Docstring?D.3.2. One-Line DocstringsD.3.3. Multi-Line DocstringsD.3.4. Handling Docstring IndentationD.4. CopyrightD.5. Acknowledgments
E. PEP 387: Backwards Compatibility Policy
E.1. AbstractE.2. RationaleE.3. Backwards Compatibility RulesE.4. Making Incompatible ChangesE.5. Copyright
F. PEP 3000: Python 3000
F.1. AbstractF.2. NamingF.3. PEP NumberingF.4. TimelineF.5. Compatibility and TransitionF.6. Implementation LanguageF.7. Meta-ContributionsF.8. Copyright
G. PEP 3003: Python Language Moratorium
G.1. AbstractG.2. RationaleG.3. DetailsG.3.1. Cannot ChangeG.3.2. Case-by-Case ExemptionsG.3.3. Allowed to ChangeG.4. RetroactiveG.5. ExtensionsG.6. Copyright

Content preview from Pro Python

Chapter 8. Documentation

Documentation is arguably the most difficult part of any project. Code tends to come fairly easy to programmers, but documentation requires a different set of skills because the audience is strictly human. The magnitude of the differences can vary greatly between projects and audiences. Sometimes all that's necessary is some example code, while other topics can fill entire books and still have plenty left to cover.

The language of documentation is very different from that of code, so it can be difficult to excel at both. This causes many programmers to take the path of least resistance, opting for tools that automatically generate some minimal form of documentation from the code itself, so the extra work is kept to a minimum. ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

O’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.

Julian F.

Head of Cybersecurity

I wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.

Addison B.

Field Engineer

I’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.

Amir M.

Data Platform Tech Lead

I'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.

Mark W.

Embedded Software Engineer

Python: Essential Reference, Third Edition

Publisher Resources

ISBN: 9781430227571Purchase book

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills

Pro Python

by Marty Alchin

Chapter 8. Documentation

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.