Python Best Practices: Understanding PEPs and Coding Conventions, Study notes of Design

Download Python Best Practices: Understanding PEPs and Coding Conventions and more Study notes Design in PDF only on Docsity! eden ee @irror_mod.use_y Mirror_mod.use z lection at the end ars WP_ob.select= 1 "ier_ob.select=1 eee Mes ace las ee rac ee (eae ror_ob.select Good Coding Practices Daniel Perrefort - University of Pittsburgh bpy - context. sele< ta.objects[one. int(“please Pry ave lS et a7 -W Lan What is a Best Practice?  Best practices are any procedure that is accepted as being the most effective either by consensus or by prescription.  Practices can range from stylistic to in-depth design methodologies. "A universal convention supplies all of maintainability, clarity, consistency, and a foundation for good programming habits too." —Tim Peters on comp.lang.python, 2001-06-16 PEP 20: The Zen of Python Beautiful is better than ugly. Explicit is better than implicit. Simple is better than complex. Complex is better than complicated. Flat is better than nested. Sparse is better than dense. Readability counts. Special cases aren't special enough to break the rules. Although practicality beats purity. Errors should never pass silently. Unless explicitly silenced. In the face of ambiguity, refuse the temptation to guess. There should be one-- and preferably only one --obvious way to do it. Although that way may not be obvious at first unless you're Dutch. Now is better than never. Although never is often better than *right* now. If the implementation is hard to explain, it's a bad idea. If the implementation is easy to explain, it may be a good idea. Namespaces are one honking great idea -- let's do more of those! >>> import this PEP 8: Style Guide for Python Code Code is read much more often than it is written. Easy to read means easier to develop. Well written code conveys professionalism. Code is a deliverable part of your project! PEP8: Code Layout  Using 4 spaces per indentation level (not tabs!)  Putting two blank lines before functions and classes  Limiting line lengths to:  79 characters for code  72 characters for long blocks of text  It is okay to increase the line length limit up to 99 characters Your probably already familiar with… PEP8: General Recommendations  Use ̀ is` when comparing singletons  Use ̀ is not` instead of ̀ not ... is` # Wrong if foo == None: do_something() # Also wrong if not foo is None: do_something() # Correct if foo is not None: do_something() PEP8: General Recommendations  Always use a `def` statement instead of an assignment statement for anonymous (lambda) expressions # Wrong f = lambda x: 2 * x # Correct def double(x): return 2 * x PEP8: General Recommendations  Derive exceptions from `Exception` rather than `BaseException`  Use explicit exception catching (avoid bare exceptions)  Keep `try` statements as simple as possible # Wrong try: import platform_specific_module my_function() except: platform_specific_module = None # Correct try: import platform_specific_module except ImportError: platform_specific_module = None else: my_function() PEP 257: Docstring Conventions Documentation is key to reusable code Never assume you will remember what your code does (or how it works) Documentation can include technical notes and derivations. Saves you headaches when you revisit a project in part or in whole Good Documentation Should…  Explain what each function / module / package does or is responsible for  Be understandable to you when you revisit the code in 6 months  Be understandable by someone new to the project (but not necessarily new to the subject matter)  Be specific and to the point PEP257: Single Line Docs  Triple quotes are always used  The closing quotes are on the same line as the opening quotes.  The docstring is a phrase ending in a period. It prescribes the function’s effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname . def kos_root(): """Return the pathname of the KOS root directory.""" ... Document the Code AND the Project  Extensive project documentation isn’t always necessary and should scale to meet your project requirements.  Include a README file at minimum  Describe the project goals and general approach  Does not need to be super in depth  For larger projects, you might document:  Design choices or style guides  Project notes (e.g. from papers you read)  A development plan / roadmap Side Note  Use tools like Sphinx and Read The Docs to generate automatic documentation  Sphinx: https://www.sphinx-doc.org/  RTD: https://readthedocs.org  Running the setup script: $ pip install sphinx $ sphinx-quickstart PEP 484: Type Hints  “New” as of Python 3.5  Not extensively used but can be extremely helpful for  Adding inspection support when developing API’s  Enforcing type linting in your own projects Type hints are probably not a “best practice” but planning out your code ahead of time (e.g. function signatures) is! from typing import Union PathLike = Union[str, Path] def greeting(name: str) -> str: return 'Hello ' + name def process_directory(path: PathLike): return 'Hello ' + name The Infamous “Scripts” Directory  Scripts should NOT be where your analysis logic is  Scripts should NOT be a dumping ground for scratch code  Each script should represent a single distinct task. For e.g.,  Run image calibration  Fit object light-curves  Download / format data from a remote server  Include (short) module level docs for each script Use Version Control  Allows easier collaboration, especially with large teams.  Provides descriptions of each change and why it was made.  Backs up your project incase something goes wrong.  You can revert changes or recover previous code. gi t cl ean - n Show s w hich fil es w ould be removed from w orking directory. Use the - f flag in place of the - n flag to execute the clean. Push the branch t o <r emot e>, along w ith necessary commit s and object s. Creates named branch in the remote repo if it doesn’t exist . gi t push <r emot e> <br anch> gi t r eset <f i l e> Remove <f i l e> from the staging area, but leave the working directory unchanged. This unstages a file w ithout overw rit ing any changes. gi t pul l <r emot e> Fetch the specified remote’s copy of current branch and immediat ely merge it into the local copy. gi t r ever t <commi t > Create new commit that undoes all of the changes made in <commi t >, t hen apply it t o the current branch. gi t f et ch <r emot e> <br anch> Fetches a specific <br anch>, from the repo. Leave off <br anch> to fetch all remote refs. gi t r emot e add <name> <ur l > Create a new connect ion t o a remote repo. Aft er adding a remote, you can use <name> as a shortcut for <ur l > in other commands. gi t di f f Show unst aged changes bet w een your index and w orking directory. gi t commi t - m " <message>" Commit the st aged snapshot , but inst ead of launching a text edit or, use <message> as the commit message. UNDOING CHANGES gi t st at us List w hich files are staged, unst aged, and unt racked. REMOTE REPOSITORIES gi t l og Display the ent ire commit hist ory using the default format . For cust omizat ion see addit ional opt ions. gi t br anch List all of the branches in your repo. Add a <br anch> argument t o create a new branch w ith the name <br anch>. gi t checkout - b <br anch> Create and check out a new branch named <br anch>. Drop the - b flag to checkout an exist ing branch. gi t mer ge <br anch> Merge <br anch> into the current branch. gi t add <di r ect or y> Stage all changes in <di r ect or y> for the next commit . Replace <di r ect or y> w ith a <f i l e> to change a specific fil e. gi t cl one <r epo> gi t conf i g user . name <name> GIT BRANCHES Define author name t o be used for all commit s in current repo. Devs commonly use - - gl obal flag to set config opt ions f or current user. gi t r ebase <base> gi t r ef l og Show a log of changes t o the local repository’s HEAD. Add - - r el at i ve- dat e flag to show date info or - - al l to show all refs. Clone repo located at <r epo> onto local machine. Original repo can be located on the local filesystem or on a remote machine via HTTP or SSH. gi t i ni t <di r ect or y> Create empty Git repo in specified directory. Run w ith no arguments to init ialize the current directory as a git repository. gi t commi t - - amend Replace the last commit w ith the staged changes and last commit combined. Use w ith nothing st aged to edit the last commit ’s message. Rebase the current branch ont o <base>. <base> can be a commit ID, branch name, a t ag, or a relat ive reference to HEAD. GIT BASICS REWRITING GIT HISTORY Git Cheat Sheet Visit at lassian.com/git for more informat ion, t raining, and tutorials Put one of these at your desk! (atlassian)