From 083176894cae08fad4c4111c81fc6c8cd5653a32 Mon Sep 17 00:00:00 2001 From: Tyler Veness Date: Thu, 14 Jul 2022 21:30:22 -0700 Subject: [PATCH] Remove Python styleguide (#229) We use black for formatting now instead of a tool that follows Google's Python styleguide, so the included HTML is no longer relevant. --- README.md | 2 +- pyguide.css | 146 --- pyguide.html | 2771 -------------------------------------------------- 3 files changed, 1 insertion(+), 2918 deletions(-) delete mode 100644 pyguide.css delete mode 100644 pyguide.html diff --git a/README.md b/README.md index b2fc84a0..53c8f34a 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ This repository contains our style guides for C++ and Java code, various IDE sup Anything submitted to a wpilibsuite project needs to follow the code style guides outlined here. For details about the style, please see the contributors document [here](CONTRIBUTING.md#coding-guidelines). -Style configuration files for IDEs are in the [ide](ide) folder. The style guides for C++, Java, and Python are named `cppguide`, `javaguide`, and `pyguide` respectively. +Style configuration files for IDEs are in the [ide](ide) folder. The style guides for C++ and Java are named `cppguide` and `javaguide` respectively. ## Setup diff --git a/pyguide.css b/pyguide.css deleted file mode 100644 index f5d7a63c..00000000 --- a/pyguide.css +++ /dev/null @@ -1,146 +0,0 @@ -body { - background-color: #fff; - color: #333; - font-family: sans-serif; - font-size: 10pt; - margin-right: 100px; - margin-left: 100px; -} - -h1, h2, h3, h4, h5, h6, .toc_title { - color: #06c; - margin-top: 2em; - margin-bottom: 1em; -} - -h1 { - text-align: center; - font-size: 18pt; -} - -h2, .toc_title { - font-weight: bold; - font-size: 12pt; - margin-left: -40px; -} - -h3, h4, h5, h6 { - font-size: 10pt; - margin-left: -20px; -} - -.toc_category, .toc_stylepoint { - font-size: 10pt; - padding-top: .3em; - padding-bottom: .3em; -} - -table { - border-collapse: collapse; -} - -td, th { - border: 1px solid #ccc; - padding: 2px 12px; - font-size: 10pt; -} - -.toc td, .toc th { - border-width: 1px 5px; -} - -code, samp, var { - color: #060; -} - -pre { - font-size: 10pt; - display: block; - color: #060; - background-color: #f8fff8; - border-color: #f0fff0; - border-style: solid; - border-top-width: 1px; - border-bottom-width: 1px; - border-right-width: 1px; - border-left-width: 5px; - padding-left: 12px; - padding-right: 12px; - padding-top: 4px; - padding-bottom: 4px; -} - -pre.badcode { - color: #c00; - background-color: #fff8f8; - border-color: #fff0f0; -} - -.showhide_button { - float: left; - cursor: pointer; - border-width: 1px; - border-style: solid; - border-color: #ddd #aaa #aaa #ddd; - padding: 0 3px 1px; - margin: 0 4px 8px 0; - border-radius: 3px; - -webkit-border-radius: 3px; - -moz-border-radius: 3px; -} - -.link_button { - float: left; - display: none; - background-color: #f8f8ff; - border-color: #f0f0ff; - border-style: solid; - border-width: 1px; - font-size: 75%; - margin-top: 0; - margin-left: -50px; - padding: 4px; - border-radius: 3px; - -webkit-border-radius: 3px; - -moz-border-radius: 3px; -} - -address { - text-align: right; -} - -hr { - margin-top: 3.5em; - border-width: 1px; - color: #fff; -} - -.stylepoint_section { - display: block; - margin-bottom: 1em; - color: #5588ff; - font-family: sans-serif; - font-size: 90%; - font-weight: bold; - margin-left: -2%; -} - -.stylepoint_subsection { - color: #667799; - font-family: sans-serif; - font-size: 90%; - font-weight: bold; - margin-left: -1%; -} - -.stylepoint_subsubsection { - color: #667799; - font-family: sans-serif; - font-size: 80%; - font-weight: bold; - margin-left: 0; -} - -.revision { - text-align: right; -} diff --git a/pyguide.html b/pyguide.html deleted file mode 100644 index 036dd6d6..00000000 --- a/pyguide.html +++ /dev/null @@ -1,2771 +0,0 @@ - - - - - Google Python Style Guide - - - - - - - -

- Google Python Style Guide -

-

- Revision 2.59 -

-
- Amit Patel
- Antoine Picard
- Eugene Jhong
- Jeremy Hylton
- Matt Smart
- Mike Shields
-
-
-

- Each style point has a summary for which additional information is - available by toggling the accompanying arrow button that looks this - way: ▶. You may toggle all summaries - with the big arrow button: -

-
- ▶ Toggle all summaries -
-
-
-
- Table of Contents -
- - - - - - - - - -
-
- Python Language Rules -
- 		-
- Lint Imports Packages Exceptions Global variables Nested/Local/Inner - Classes and Functions List Comprehensions - Default Iterators - and Operators Generators Lambda Functions Conditional Expressions - Default Argument - Values Properties True/False evaluations - Deprecated Language - Features Lexical Scoping Function and Method - Decorators Threading Power Features -
-
-
- Python Style Rules -
- 		-
- Semicolons Line length Parentheses Indentation Blank Lines Whitespace Shebang Line Comments Classes Strings Files and Sockets TODO Comments Imports formatting Statements Access Control Naming Main -
-
-
-
-

- Important Note -

-
-

- Displaying Hidden Details - in this Guide -

link - ▶ -
- This style guide contains many details that are initially hidden from - view. They are marked by the triangle icon, which you see here on - your left. Click it now. You should see "Hooray" appear below. -
-
-
-

- Hooray! Now you know you can expand points to get more details. - Alternatively, there's a "toggle all" at the top of this - document. -

-
-
-
-
-
-

- Background -

-

- Python is the main scripting language used at Google. This style guide - is a list of dos and don'ts for Python programs. -

-

- To help you format code correctly, we've created a settings file for Vim. For Emacs, the - default settings should be fine. -

-
-
-

- Python Language Rules -

-
-

- Lint -

link - ▶ -
- Run pylint over your code. -
-
-
-

- Definition: pylint is a - tool for finding bugs and style problems in Python source code. - It finds problems that are typically caught by a compiler for - less dynamic languages like C and C++. Because of the dynamic - nature of Python, some warnings may be incorrect; however, - spurious warnings should be fairly infrequent. -

-

- Pros: Catches - easy-to-miss errors like typos, using-vars-before-assignment, - etc. -

-

- Cons: pylint - isn't perfect. To take advantage of it, we'll need to sometimes: - a) Write around it b) Suppress its warnings or c) Improve it. -

-

- Decision: Make sure you - run pylint on your code. Suppress warnings if they - are inappropriate so that other issues are not hidden. -

-

- To suppress warnings, you can set a line-level comment: -

-
- 
-dict = 'something awful'  # Bad Idea... pylint: disable=redefined-builtin
-
-

- pylint warnings are each identified by a alphanumeric code - (C0112) and a symbolic name - (empty-docstring). Prefer the symbolic names in new - code or when updating existing code. -

-

- If the reason for the suppression is not clear from the symbolic - name, add an explanation. -

-

- Suppressing in this way has the advantage that we can easily - search for suppressions and revisit them. -

-

- You can get a list of pylint warnings by doing pylint - --list-msgs. To get more information on a particular - message, use pylint --help-msg=C6409. -

-

- Prefer pylint: disable to the deprecated older form - pylint: disable-msg. -

-

- Unused argument warnings can be suppressed by using `_' as the - identifier for the unused argument or prefixing the argument name - with `unused_'. In situations where changing the argument names - is infeasible, you can mention them at the beginning of the - function. For example: -

-
- 
-def foo(a, unused_b, unused_c, d=None, e=None):
-    _ = d, e
-    return a
-
-
-
-
-
-
-
-

- Imports -

link ▶ -
- Use imports for packages and modules only. -
-
- -
-
-
-

- Packages -

link ▶ -
- Import each module using the full pathname location of the module. -
-
- -
-
-
-

- Exceptions -

link ▶ -
- Exceptions are allowed but must be used carefully. -
-
- -
-
-
-

- Global variables -

link - ▶ -
- Avoid global variables. -
-
- -
-
-
-

- Nested/Local/Inner Classes - and Functions -

link - ▶ -
- Nested/local/inner classes and functions are fine. -
-
-
-

- Definition: A class can - be defined inside of a method, function, or class. A function can - be defined inside a method or function. Nested functions have - read-only access to variables defined in enclosing scopes. -

-

- Pros: Allows definition - of utility classes and functions that are only used inside of a - very limited scope. Very ADT-y. -

-

- Cons: Instances of nested - or local classes cannot be pickled. -

-

- Decision: They are fine. -

-
-
-
-
-

- List - Comprehensions -

link - ▶ -
- Okay to use for simple cases. -
-
- -
-
-
-

- Default Iterators and Operators -

link - ▶ -
- Use default iterators and operators for types that support them, like - lists, dictionaries, and files. -
-
- -
-
-
-

- Generators -

link ▶ -
- Use generators as needed. -
-
- -
-
-
-

- Lambda Functions -

link - ▶ -
- Okay for one-liners. -
-
- -
-
-
-

- Conditional Expressions -

link - ▶ -
- Okay for one-liners. -
-
- -
-
-
-

- Default Argument Values -

link - ▶ -
- Okay in most cases. -
-
- -
-
-
-

- Properties -

link ▶ -
- Use properties for accessing or setting data where you would normally - have used simple, lightweight accessor or setter methods. -
-
- -
-
-
-

- True/False evaluations -

link - ▶ -
- Use the "implicit" false if at all possible. -
-
- -
-
-
-

- Deprecated Language Features -

link - ▶ -
- Use string methods instead of the string module where - possible. Use function call syntax instead of apply. Use - list comprehensions and for loops instead of - filter and map when the function argument - would have been an inlined lambda anyway. Use for loops - instead of reduce. -
-
- -
-
-
-

- Lexical Scoping -

link ▶ -
- Okay to use. -
-
- -
-
-
-

- Function and Method Decorators -

link - ▶ -
- Use decorators judiciously when there is a clear advantage. -
-
- -
-
-
-

- Threading -

link ▶ -
- Do not rely on the atomicity of built-in types. -
-
- -
-
-
-

- Power Features -

link ▶ -
- Avoid these features. -
-
- -
-
-
-
-

- Python Style Rules -

-
-

- Semicolons -

link ▶ -
- Do not terminate your lines with semi-colons and do not use - semi-colons to put two commands on the same line. -
-
- -
-
-
-

- Line length -

link ▶ -
- Maximum line length is 80 characters. -
-
- -
-
-
-

- Parentheses -

link ▶ -
- Use parentheses sparingly. -
-
- -
-
-
-

- Indentation -

link ▶ -
- Indent your code blocks with 4 spaces. -
-
- -
-
-
-

- Blank Lines -

link ▶ -
- Two blank lines between top-level definitions, one blank line between - method definitions. -
-
- -
-
-
-

- Whitespace -

link ▶ -
- Follow standard typographic rules for the use of spaces around - punctuation. -
-
- -
-
-
-

- Shebang Line -

link ▶ -
- Most .py files do not need to start with a - #! line. Start the main file of a program with - #!/usr/bin/env python with an optional single digit - 2 or 3 suffix. -
-
- -
-
-
-

- Comments -

link ▶ -
- Be sure to use the right style for module, function, method and - in-line comments. -
-
- -
-
-
-

- Classes -

link ▶ -
- If a class inherits from no other base classes, explicitly inherit - from object. This also applies to nested classes. -
-
- -
-
-
-

- Strings -

link ▶ -
- Use the format method or the % operator for - formatting strings, even when the parameters are all strings. Use - your best judgement to decide between + and - % (or format) though. -
-
- -
-
-
-

- Files and - Sockets -

link - ▶ -
- Explicitly close files and sockets when done with them. -
-
- -
-
-
-

- TODO Comments -

link ▶ -
- Use TODO comments for code that is temporary, a - short-term solution, or good-enough but not perfect. -
-
- -
-
-
-

- Imports - formatting -

link - ▶ -
- Imports should be on separate lines. -
-
- -
-
-
-

- Statements -

link ▶ -
- Generally only one statement per line. -
-
- -
-
-
-

- Access Control -

link ▶ -
- If an accessor function would be trivial you should use public - variables instead of accessor functions to avoid the extra cost of - function calls in Python. When more functionality is added you can - use property to keep the syntax consistent. -
-
- -
-
-
-

- Naming -

link - ▶ -
- module_name, package_name, ClassName, method_name, - ExceptionName, function_name, GLOBAL_CONSTANT_NAME, global_var_name, - instance_var_name, function_parameter_name, local_var_name. -
-
- -
-
-
-

- Main -

link - ▶ -
- Even a file meant to be used as a script should be importable and a - mere import should not have the side effect of executing the script's - main functionality. The main functionality should be in a main() - function. -
-
-
-

- In Python, pydoc as well as unit tests require - modules to be importable. Your code should always check if - __name__ == '__main__' before executing your main program - so that the main program is not executed when the module is - imported. -

-
- 
-def main():
-      ...
-
-if __name__ == '__main__':
-    main()
-
-
-
-

- All code at the top level will be executed when the module is - imported. Be careful not to call functions, create objects, or - perform other operations that should not be executed when the - file is being pydoced. -

-
-
-
-
-

- Parting Words -

-

- BE CONSISTENT. -

-

- If you're editing code, take a few minutes to look at the code around you - and determine its style. If they use spaces around all their arithmetic - operators, you should too. If their comments have little boxes of hash - marks around them, make your comments have little boxes of hash marks - around them too. -

-

- The point of having style guidelines is to have a common vocabulary of - coding so people can concentrate on what you're saying rather than on how - you're saying it. We present global style rules here so people know the - vocabulary, but local style is also important. If code you add to a file - looks drastically different from the existing code around it, it throws - readers out of their rhythm when they go to read it. Avoid this. -

-

- Revision 2.59 -

-
- Amit Patel
- Antoine Picard
- Eugene Jhong
- Gregory P. Smith
- Jeremy Hylton
- Matt Smart
- Mike Shields
- Shane Liebling
-
- -