This specification is based on PEP8 Based on , Refer to Huawei Python Generic coding specification 、 Safety programming specification , Combined with the consensus of the industry , Participate in MindSpore Community development needs to follow the contents of this specification first （ And PEP8 The conflict part ）, Others follow PEP8 standard .
If you disagree with the rules , It is recommended to submit issue And explain why , the MindSpore After the community operation team reviews and accepts it, it can be modified and take effect .
a
MindSpore The open source community
The rules 1.1.1 Package name , Module name ： A lowercase letter , Don't underline .
The rules 1.1.2 Class name ： Use hump format , title case , Private class underscore prefix .
class _Foo:
_instance = None
pass
The rules 1.1.3 Function name 、 Variable name ： A lowercase letter , Multiple word underline segmentation .
def _func_example(path):
pass
Suggest 1.1.4 Except iterators and counters , Single character naming is prohibited .
The rules 1.2.1 Do not exceed... Characters per line 120 individual .
If exceeded 120 Characters , Please choose a reasonable way to wrap .
The rules 1.2.2 Indent with spaces , Every indent 4 A space , prohibit tab Indent .
The rules 1.2.3 import The order ： Standard library 、 The third party 、 Custom module .
The rules 1.2.4 Return statements and conditional statements do not use parentheses .
The rules 1.2.5 Double blank lines between module level functions and classes , A blank line between class member functions , Add blank lines between comments and code as needed , In principle, no more than two blank lines .
The rules 1.2.6 Invalid or redundant codes are deleted directly , Do not comment 、TODO And so on , Suggestion issue Record .
The rules 1.3.1 File header comments must contain a copyright notice .
all python file , Must contain the following copyright notice ：
# Copyright 2019 Huawei Technologies Co., Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ============================================================================
""" Add notes. """
import xxx
About copyright notes , Attention should be paid to ：
2020 Files created in , Should beCopyright 2020 Huawei Technologies Co., Ltd
2019 Year year of creation ,2020 Year change year , Should beCopyright 2019-2020 Huawei Technologies Co., Ltd
The rules 1.3.2 The external class 、 Method 、 operator 、Cell Annotation format .
class and def The format of the comment is the same , Adopt the industry general python Annotation syntax , Write below the statement and indent , be-all class and def Need to write notes , The classes and methods inside the module can only write a brief introduction .The rules 1.3.3 Note masking is not allowed pylint The alarm .
The rules 1.4.1 Exception log text is capitalized .
The rules 1.4.2 The variable name in the log text must be indicated in single quotation marks .
The rules 2.1.1 The user interface is in the file __all__ Description in ,__all__ Put in import And code .
The rules 2.1.2 The non external method used in the current file is named with the underscore prefix , Methods used internally across modules do not require an underscore prefix , User interface in __all__ In a statement .
The rules 2.2.1 Check the validity of all external data , Including but not limited to ： Function into the reference 、 External input named lines 、 File format , file size 、 environment variable 、 User data, etc .
Suggest 2.2.2 The file path must be normalized before use .
When the file path comes from external data , You need to normalize the file path first , If there is no normalization , The attacker has the opportunity to access the file beyond his authority by maliciously constructing the file path ：
for example , An attacker can construct “…/…/…/etc/passwd” To access arbitrary files .
stay linux Next , Use realpath function , stay windows Next , Use PathCanonicalize Function to normalize the file path .
The rules 2.2.3 Ban called OS A command parser executes a command or runs a program .
Use unverified untrusted input as a parameter of a system command or as part of a command , May lead to command injection vulnerability . For command injection vulnerability , The command will be with Python The application executes at the same privilege level , It provides attackers with a similar system shell The function of . stay Python in ,os.system or os.popen It is often used to call a new process , If the command to be executed comes from an external input , Command and parameter injection may occur .
When executing an order , Please pay attention to the following points ：
【 Error code example 1】
An attacker can find environment variables by APPHOME Corresponding value , And put constants in the corresponding directory INITCMD Corresponding attack program , Achieve the effect of implementation ：
home = os.getenv('APPHOME')
cmd = os.path.join(home, INITCMD)
os.system(cmd)
【 Error code example 2】
There is no validation property backuptype Value , This is entered by the user , An attacker may attack ,
for example ： User input is ：" && del c:\dbms\. "：
# The value comes from the user configuration
btype = req.field('backuptype')
cmd = "cmd.exe /K \"c:\\util\\rmanDB.bat " + btype + "&&c:\\util\\cleanup.bat\""
os.system(cmd)
【 Error code example 3】
There is no validation property backuptype Value , This is entered by the user , An attacker may attack , for example ： User input is ：" && del c:\dbms\. "：
import os
import sys
try:
print(os.system("ls " + sys.argv[1]))
except Exception as ex:
print('exception:', ex)
An attacker can exploit this vulnerable program through the following command ：
python test.py ". && echo bad"
Two commands will actually be executed ：
ls .
echo bad
【 Examples of correct code 】
Avoid using os.system, You can use standard API Instead of running system commands to complete tasks ：
import os
import sys
try:
print(os.listdir(sys.argv[1]))
except Exception as ex:
print(ex)
The rules 2.3.1 Exceptions must be handled properly , Suppresses or ignores checked exceptions .
every last except Blocks should ensure that the program will only continue to run if it continues to be valid .except The block must either recover from an exception , Or re throw the appropriate current catch Another exception to the block context to allow the nearest outer layer try-except Statement block for recovery work .
【 Examples of correct code 】
The right thing to do is , Avoid using os.system, You can use standard API Instead of running system commands to complete tasks ：
validFlag = False
while not validFlag:
try:
# If requested file does not exist, throws FileNotFoundError
# If requested file exists, sets validFlag to true
validFlag = True
except FileNotFoundError:
import traceback
traceback.print_exc()
【 Exceptions 】：
The rules 2.3.2 Use try…except… When structures protect code , You need to use after an exception finally… Structure guarantees the release of the operation object .
Use try…except… When structures protect code , If an exception occurs during code execution , In order to reliably close the operation object , Need to use finally… Structure ensures that the operand is released .
【 Examples of correct code 】
handle = open(r"/tmp/sample_data.txt") # May raise IOError
try:
data = handle.read() # May raise UnicodeDecodeError
except UnicodeDecodeError as decode_error:
print(decode_error)
finally:
handle.close() # Always run after try:
The rules 2.3.3 Do not use “except:” Statement to catch all exceptions .
In terms of anomalies , Python Very tolerant ,“except:” The statement will really capture including Python Any error, including grammatical errors . Use “except:” It's easy to hide the real bug, We are using try…except… When structures protect code , You should specify the exceptions you expect to handle .Exception Class is the base class for most runtime exceptions , It should also be avoided in general except Use in statement . Usually ,try Only statements that must handle exceptions in the current location should be included ,except Catch only exceptions that must be handled . For example, for the code that opens the file ,try Should contain only open sentence ,except Capture only FileNotFoundError abnormal . For other unexpected exceptions , Then let the upper function capture , Or it can be transmitted to the outside of the program to fully expose the problem .
【 Error code example 】
The following code may throw two types of exceptions , Use “except:” Statement for unified processing , If it is open Perform abnormal , Will be in “except:” After statement handle Call... When it is invalid close, Report errors handle Undefined .
try:
handle = open(r"/tmp/sample_data.txt") # May raise IOError
data = handle.read() # May raise UnicodeDecodeError
except:
handle.close()
【 Examples of correct code 】
try:
handle = open(r"/tmp/sample_data.txt") # May raise IOError
try:
data = handle.read() # May raise UnicodeDecodeError
except UnicodeDecodeError as decode_error:
print(decode_error)
finally:
handle.close()
except(FileNotFoundError, IOError) as file_open_except:
print(file_open_except)
The rules 2.3.4 be not in except Inside the branch raise Must bring an exception .
raise Keywords used alone can only appear in try-except In the sentence , Rethrow except Catch the exception .
【 Error code example 】
a = 1
if a == 1:
raise
【 Examples of correct code 1】raise One Exception Or custom Exception
a = 1
if a == 1:
raise Exception
【 Examples of correct code 2】 stay try-except Use in statement
try:
f = open('myfile.txt')
s = f.readline()
i = int(s.strip())
except IOError as e:
print("I/O error({0}): {1}".format(e.errno, e.strerror))
except ValueError:
print("Could not convert data to an integer.")
except Exception:
print("Unexpected error:", sys.exc_info()[0])
raise
The rules 2.4.1 pickle There are security issues , No use pickle.load、cPickle.load and shelve The module loads untrusted data .
The rules 2.4.2 Use safe random numbers .
Python The function of generating random numbers is random Module implementation , A pseudo-random number generator with various distributions is implemented . The resulting random number can be uniformly distributed , Gaussian distribution , Lognormal distribution , Negative exponential distribution and alpha,beta Distribution , But these random numbers are pseudorandom numbers , It cannot be used in applications for security encryption purposes .
Please use /dev/random Generating safe random numbers , Or use it in python 3.6 Version officially introduced secrets The module generates a safe random number .
【 Error code example 】
import random
# Pseudo random number
func = random.SystemRandom()
print(func.random())
print(func.randint(0, 10))
【 Examples of correct code 】
import platform
# Please refer to the cryptographic algorithm specification for the length , Different scenes require different lengths
randLength = 16
if platform.system() == 'Linux':
with open("/dev/random", 'rb') as file:
sr = file.read(randLength)
print(sr)
The rules 2.4.3 assert Statements are usually used only in test code , Do not use Release The version contains assert function .
assert It should only be used for internal testing during development , There is AssertionError An exception indicates a software design or coding error , The software should be modified to solve . It is forbidden to include in the externally released production version assert function .
