构建Python包的五个简单准则简介

# ORDER MATTERS HERE -- SOME MODULES ARE DEPENDANT ON OTHERS
# 导入顺序要考虑——一些模块会依赖另外的一些
from exceptions import FSQError, FSQEnvError, FSQEncodeError,
            FSQTimeFmtError, FSQMalformedEntryError,
            FSQCoerceError, FSQEnqueueError, FSQConfigError,
            FSQPathError, FSQInstallError, FSQCannotLockError,
            FSQWorkItemError, FSQTTLExpiredError,
            FSQMaxTriesError, FSQScanError, FSQDownError,
            FSQDoneError, FSQFailError, FSQTriggerPullError,
            FSQHostsError, FSQReenqueueError, FSQPushError 
 
# constants relies on: exceptions, internal
import constants
 
# const relies on: constants, exceptions, internal
from const import const, set_const 
# has tests
 
# path relies on: exceptions, constants, internal
import path 
# has tests
 
# lists relies on: path
from lists import hosts, queues
 
#...

__all__ = [ 'FSQError', 'FSQEnvError', 'FSQEncodeError', 'FSQTimeFmtError',
      'FSQMalformedEntryError', 'FSQCoerceError', 'FSQEnqueueError',
      'FSQConfigError', 'FSQCannotLock', 'FSQWorkItemError',
      'FSQTTLExpiredError', 'FSQMaxTriesError', 'FSQScanError',
      'FSQDownError', 'FSQDoneError', 'FSQFailError', 'FSQInstallError',
      'FSQTriggerPullError', 'FSQCannotLockError', 'FSQPathError',
      'path', 'constants', 'const', 'set_const', 'down', 'up',
      
# ...
     ]

class APackageException(Exception):
  
'''root for APackage Exceptions, only used to except any APackage error, never raised'''
  pass

try:
  
'''bunch of code from your package'''
except APackageException:
  
'''blanked condition to handle all errors from your package'''

# from fsq
class FSQEnvError(FSQError):
  
'''An error if something cannot be loaded from env, or env has an invalid
    
value'''
  pass
 
class FSQEncodeError(FSQError):
  
'''An error occured while encoding or decoding an argument'''
  pass
# ... and 20 or so more

# this
try:
  item = fsq.senqueue('queue', 'str', 'arg', 'arg')
  scanner = fsq.scan('queue')
except FSQScanError:
  
'''do something'''
except FSQEnqueueError:
  
'''do something else'''
 
# not this
try:
  item = fsq.senqueue('queue', 'str', 'arg', 'arg')
except FSQEnqueueError:
  
'''do something else'''
try:
  scanner = fsq.scan('queue')
except FSQScanError:
  
'''do something'''
 
# and definitely not
try:
  item = fsq.senqueue('queue', 'str', 'arg', 'arg')
  try:
    scanner = fsq.scan('queue')
  except FSQScanError:
    
'''do something'''
except FSQEnqueueError:
  
'''do something else'''

# within a sub-module
from a_package import APackageError

# within a sub-module 
from . import FSQEnqueueError, FSQCoerceError, FSQError, FSQReenqueueError,
       constants as _c, path as fsq_path, construct,
       hosts as fsq_hosts, FSQWorkItem
from .internal import rationalize_file, wrap_io_os_err, fmt_time,
           coerce_unicode, uid_gid
# you can also use ../... etc. in sub-packages.

class APackageClass(object):
  
'''One class'''
 
def apackage_builder(how_many):
  for i in range(how_many):
    yield APackageClass()

####### EXPOSED METHODS #######
def enqueue(trg_queue, item_f, *args, **kwargs):
  
'''Enqueue the contents of a file, or file-like object, file-descriptor or
    
the contents of a file at an address (e.g. '/my/file') queue with
    
arbitrary arguments, enqueue is to venqueue what printf is to vprintf
  
'''
  return venqueue(trg_queue, item_f, args, **kwargs)
 
def senqueue(trg_queue, item_s, *args, **kwargs):
  
'''Enqueue a string, or string-like object to queue with arbitrary
    
arguments, senqueue is to enqueue what sprintf is to printf, senqueue
    
is to vsenqueue what sprintf is to vsprintf.
  
'''
  return vsenqueue(trg_queue, item_s, args, **kwargs)
 
def venqueue(trg_queue, item_f, args, user=None, group=None, mode=None):
  
'''Enqueue the contents of a file, or file-like object, file-descriptor or
    
the contents of a file at an address (e.g. '/my/file') queue with
    
an argument list, venqueue is to enqueue what vprintf is to printf
    
if entropy is passed in, failure on duplicates is raised to the caller,
    
if entropy is not passed in, venqueue will increment entropy until it
    
can create the queue item.
  
'''
  
# setup defaults
  trg_fd = name = None
  
# ...