i have rewritten one of my module files to use docstrings for the function documentation, instead of comments i had in a past posting. they are still formatted for some existing documentation handling programs i already have (which should be easy to add docstring handling to).
edit: updated file
405 lines, 12498 characters, aef5ba3c38f6bb039ef04cc77cd323d8
405 lines, 12495 characters, 8b2600c51e04328dd7fc321a264bac
link (new code)
edit: updated file
#!/usr/bin/env python # -*- coding: utf-8 -*- from __future__ import division, print_function """ file pyutils.py purpose collection of my useful python stuff email 10054452614123394844460370234029112340408691 The intent is that this module works corrently under both Python 2 and Python 3. Please report failures or code improvement to the author. """ __license__ = """ Copyright (C) 2016, by Phil D. Howard - all other rights reserved Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA, OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE, OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. The author may be contacted by decoding the number 10054452614123394844460370234029112340408691 """ import base64 from base64 import b16decode, b16encode from base64 import b32decode, b32encode from base64 import b64decode, b64encode import datetime import decimal from decimal import Decimal, InvalidOperation import hashlib from hashlib import sha256, sha384, sha512 import json from numbers import Number import os import pickle import random from random import randint import signal from signal import SIGKILL, SIGTERM import subprocess from subprocess import call, PIPE, Popen import sys from sys import argv, stderr, stdin, stdout, version_info import time from time import sleep cd = os.chdir env = os.environ now = datetime.datetime.now __y__=('ano','bai','da','ie','ja','jah','jes','kylla','oui','si','sim','taip','tak','yes') __n__=('dim','ei','ez','ingen','inno','nao','ne','nee','nei','nein','nej','neniu','nie','no','non','nu') __t__=('cierto','egia','ekte','ikke','istina','pravi','rigtigt','sann','satt','totta','true','vera','veraj','verdade','veritable','vero','vrai','waar','wahr','wier') __f__=('falsa','falsch','false','falsk','falso','faux','lazan','rangar','sbagliate','vaara','vals') __yt__=set(__y__+__t__) __nf__=set(__n__+__f__) # deprecated, no docstrings: if 'i_want_old_deprecated_isxxx_functions' in locals(): def isstr(x): return True if 'split' in dir(x) else False def isdict(x): return True if 'items' in dir(x) else False def isanylist(x): return False if 'split' in dir(x) else True if 'index' in dir(x) else False def isonlylist(x): return False if 'split' in dir(x) else True if 'sort' in dir(x) else False def istuple(x): return False if 'sort' in dir(x) else True if 'index' in dir(x) else False def isint(x): return True if 'bit_length' in dir(x) else False def isfloat(x): return True if 'is_integer' in dir(x) else False def isdecimal(x): return True if 'radix' in dir(x) else False def isdatetime(x): return True if 'time' in dir(x) else False def isdate(x): return True if 'isocalendar' in dir(x) else False def isnum(x): return True if 'bit_length' in dir(x) else True if 'is_integer' in dir(x) else True if 'radix' in dir(x) else False def chunk(s,l): """ function chunk purpose split a sequence into fixed size chunks thanks j.crater, wavic, Mekire (python-forum.io) """ return [s] if l<1 else (s[0+i:l+i] for i in range(0,len(s),l)) def fint(x): """ function fint purpose convert x to an int only if x is a float with an int value """ if isinstance(x, float): if x.is_integer(): return int(x) return x def tprint( *msg, **opt ): """ function tprint purpose a print function that avoids exceptions such as bad pipelines """ try: return print( *msg, **opt ) except IOError: return None def eprint( *msg, **opt ): """ function eprint purpose like tprint() but defaults to file=sys.stderr """ if 'file' in opt: f = opt[ 'file' ] else: f = stderr return tprint( *msg, file=f, **opt ) def b16to32(x): """ function b16to32 purpose convert base 16 encoding to base 32 encoding """ return b32encode(b16decode(x.upper())).decode( 'ascii' ) def b16to64(x,*a): """ function b16to64 purpose convert base 16 encoding to base 64 encoding """ return b64encode(b16decode(x.upper()),*a).decode( 'ascii' ) def b32to16(x): """ function b32to16 purpose convert base 32 encoding to base 16 encoding """ return b16encode(b32decode(x)).decode( 'ascii' ).lower() def b32to64(x,*a): """ function b32to64 purpose convert base 32 encoding to base 64 encoding """ return b64encode(b32decode(x),*a).decode( 'ascii' ) def b64to16(x,*a): """ function b64to16 purpose convert base 64 encoding to base 16 encoding """ return b16encode(b64decode(x,*a)).decode( 'ascii' ).lower() def b64to32(x,*a): """ function b64to32 purpose convert base 64 encoding to base 32 encoding """ return b32encode(b64decode(x,*a)).decode( 'ascii' ) def mc_env( name ): """ function mc_env pupose mixed case environment lookup (UPPER CASE PREVAILS) """ if name.upper() in env: return env[ name.upper() ] if name.lower() in env: return env[ name.lower() ] if name in env: return env[ name ] return None def valid_decimal( decarg ): """ function valid_decimal purpose non-exception test if given value can be decimal.Decimal """ try: result = Decimal( decarg ) except InvalidOperation: result = None return result def unmod(n,m): """ function unmod purpose Return the remainder after subtracting the modulus note If a list or tuple of numbers is given, return in kind arguments 1 (num) number 2 (num) modulus returns (num) number - (number % modulus) example unmod(456789,1000) -> 456000 unmod(256,15) -> 240 usage unmod(seconds,3600) -> start of this hour in seconds unmod(seconds,86400) -> start of this day in seconds unmod(minutes,1440) -> start of this day in minutes """ if not isinstance( m, Number ): raise TypeError('Not a number passed to unmod() arg2: %s (modulus)' % repr(m)) if isinstance( n, (tuple,list) ): ns = [unmod(x,m) for x in n] if isinstance( n, tuple ): return tuple(ns) return ns if not isinstance( n, Number ): raise TypeError('Not a number passed to unmod() arg1: %s (value)' % repr(n)) if m == 0: raise ValueError('Zero passed to unmod() arg2 (modulus)') if m < 0: raise ValueError('Negative value passed to unmod() arg2: %s (modulus)' % repr(m)) return n - (n % m) def find_unicode(u,notfound=-1): """ function find_unicode purpose In a unicode string, find the position of the first character that requires the unicode type and cannot be represented in mere string type. returns (int) position or the value specified by notfound= """ l = len(u) for n in xrange(l): if ord(u[n]) > 127: return n return notfound def scale( new1, new2, old1, old2, value ): """ function scale purpose Change the scale of a given number arguments 1 (num) the beginning of the new scale 2 (num) the ending of the new scale 3 (num) the beginning of the old scale 4 (num) the ending of the old scale 5 (num or tuple/list/dict of nums) value(s) to be rescaled returns (like arg 5) rescaled value(s) or None """ delta = old2 - old1 if isinstance( value, tuple): t = () for v in value: t = t + ( ( (new2 - new1) * (v - old1) + (new1 * delta) ) / delta, ) return t if isinstance( value, (list,tuple) ): l = [] for v in value: l += [ ( (new2 - new1) * (v - old1) + (new1 * delta) ) / delta ] return l if isinstance( value, dict ): d = {} for k in value.keys(): d[k] = ( (new2 - new1) * (value[k] - old1) + (new1 * delta) ) / delta return d if isinstance( value, Number ): return ( (new2 - new1) * (value - old1) + (new1 * delta) ) / delta return None def plural( value, one='', not_one='s' ): """ function plural purpose Syntactic sugar to yield 's' for plural cases else '' and allow substituting other strings. usage print( 'I see %d thing%s here'%(n,plural(n)) ) print( 'il y a %d chose%s ici'%(n,plural(n)) ) print( 'Det er %d element%s her'%(n,plural(n,'','er')) ) print( 'There %s %d thing%s here'%(plural(n,'is','are'),n,plural(n)) ) """ return one if value==1 else not_one def yes_or_no(x,no=False,yes=True,unknown=None): """ function yes_or_no aliases oui_ou_non, ja_oder_nein, ja_of_nee, ja_eller_nej, ja_eller_nei purpose Determine if a given string means yes/true or no/false arguments 1: the string or value to check no= alternate value to return for no yes= alternate value to return for yes unknown= alternate value to return for unknown returns False or no= if string/value indicates no/false True or yes= if string/value indicates yes/true None or unknwon= if string/value cannot be determined note Only a few European languages are represented here. """ if x == None: return unknown if isinstance( x, Number ): # isnum also matches bool if x: return yes else: return no elif isinstance( x, str ): if x.lower() in __nf__: return no elif x.lower() in __yt__: return yes return unknown oui_ou_non = yes_or_no ja_oder_nein = yes_or_no ja_of_nee = yes_or_no ja_eller_nej = yes_or_no ja_eller_nei = yes_or_no def test_pyutils( args ): """ function test_pyutils purpose perform tests of functions in this module with results output to stdout """ alpha = '0123456789abcdefghijklmnopqrstuvwxyz' tprint( '\nTesting scale' ) for c in (-40,0,10,15.20,25,100 ): f = scale( 32,212,0,100, c ) c = scale( 0,100,32,212, f ) tprint( str(f)+'F', '==', str(c)+'C') tprint( '\nTesting plural' ) for n in (1,2,3): tprint( '' ) tprint( 'Il y a %d chose%s ici'%(n,plural(n)) ) tprint( 'Det er %d element%s her'%(n,plural(n,'','er')) ) tprint( 'There %s %d thing%s here'%(plural(n,'is','are'),n,plural(n)) ) tprint( '\nTesting oui_ou_non' ) for f in ('oui','non','yes','no','True','False','None','unknown',True,False,None,-1,0,1,2): if oui_ou_non( f ): e = True else: e = False tprint( 'for', repr(f), 'the result is', repr(e) ) tprint( '' ) for x in range(0,12): print(x,repr(list(chunk(alpha,x)))) for x in (18,36,99,0,-1,-2,-3): print(x,repr(list(chunk(alpha,x)))) tprint( '' ) return 0 def main( args ): """main""" return test_pyutils( args ) if __name__ == '__main__': result = main( argv ) stdout.flush() try: exit( int( result ) ) except ValueError: print( str( result ), file=stderr ) exit( 1 ) except TypeError: if result == None: exit( 0 ) exit( 255 ) # EOF
#!/usr/bin/env python # -*- coding: utf-8 -*- from __future__ import division, print_function """ file pyutils.py purpose collection of my useful python stuff email 10054452614123394844460370234029112340408691 The intent is that this module works corrently under both Python 2 and Python 3. Please report failures or code improvement to the author. """ __license__ = """ Copyright (C) 2016, by Phil D. Howard - all other rights reserved Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA, OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE, OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. The author may be contacted by decoding the number 10054452614123394844460370234029112340408691 """ import base64 from base64 import b16decode, b16encode from base64 import b32decode, b32encode from base64 import b64decode, b64encode import datetime import decimal from decimal import Decimal, InvalidOperation import hashlib from hashlib import sha256, sha384, sha512 import json from numbers import Number import os import pickle import random from random import randint import signal from signal import SIGKILL, SIGTERM import subprocess from subprocess import call, PIPE, Popen import sys from sys import argv, stderr, stdin, stdout, version_info import time from time import sleep cd = os.chdir env = os.environ now = datetime.datetime.now __y__=('ano','bai','da','ie','ja','jah','jes','kylla','oui','si','sim','taip','tak','yes') __n__=('dim','ei','ez','ingen','inno','nao','ne','nee','nei','nein','nej','neniu','nie','no','non','nu') __t__=('cierto','egia','ekte','ikke','istina','pravi','rigtigt','sann','satt','totta','true','vera','veraj','verdade','veritable','vero','vrai','waar','wahr','wier') __f__=('falsa','falsch','false','falsk','falso','faux','lazan','rangar','sbagliate','vaara','vals') __yt__=set(__y__+__t__) __nf__=set(__n__+__f__) # deprecated, no docstrings: if 'i_want_old_deprecated_isxxx_functions' in locals(): def isstr(x): return True if 'split' in dir(x) else False def isdict(x): return True if 'items' in dir(x) else False def isanylist(x): return False if 'split' in dir(x) else True if 'index' in dir(x) else False def isonlylist(x): return False if 'split' in dir(x) else True if 'sort' in dir(x) else False def istuple(x): return False if 'sort' in dir(x) else True if 'index' in dir(x) else False def isint(x): return True if 'bit_length' in dir(x) else False def isfloat(x): return True if 'is_integer' in dir(x) else False def isdecimal(x): return True if 'radix' in dir(x) else False def isdatetime(x): return True if 'time' in dir(x) else False def isdate(x): return True if 'isocalendar' in dir(x) else False def isnum(x): return True if 'bit_length' in dir(x) else True if 'is_integer' in dir(x) else True if 'radix' in dir(x) else False def chunk(s,l): """ function chunk purpose split a sequence into fixed size chunks thanks j.crater, wavic, Mekire (python-forum.io) """ return [s] if l<1 else (s[0+i:l+i] for i in range(0,len(s),l)) def fint(x): """ function fint purpose convert x to an int only if x is a float with an int value """ if isinstance(x, float): if x.is_integer(): return int(x) return x def tprint( *msg, **opt ): """ function tprint purpose a print function that avoids exceptions such as bad pipelines """ try: return print( *msg, **opt ) except IOError: return None def eprint( *msg, **opt ): """ function eprint purpose like tprint() but defaults to file=sys.stderr """ if 'file' in opt: f = opt[ 'file' ] else: f = stderr return tprint( *msg, file=f, **opt ) def b16to32(x): """ function b16to32 purpose convert base 16 encoding to base 32 encoding """ return b32encode(b16decode(x.upper())).decode( 'ascii' ) def b16to64(x,*a): """ function b16to64 purpose convert base 16 encoding to base 64 encoding """ return b64encode(b16decode(x.upper()),*a).decode( 'ascii' ) def b32to16(x): """ function b32to16 purpose convert base 32 encoding to base 16 encoding """ return b16encode(b32decode(x)).decode( 'ascii' ).lower() def b32to64(x,*a): """ function b32to64 purpose convert base 32 encoding to base 64 encoding """ return b64encode(b32decode(x),*a).decode( 'ascii' ) def b64to16(x,*a): """ function b64to16 purpose convert base 64 encoding to base 16 encoding """ return b16encode(b64decode(x,*a)).decode( 'ascii' ).lower() def b64to32(x,*a): """ function b64to32 purpose convert base 64 encoding to base 32 encoding """ return b32encode(b64decode(x,*a)).decode( 'ascii' ) def mc_env( name ): """ function mc_env pupose mixed case environment lookup (UPPER CASE PREVAILS) """ if name.upper() in env: return env[ name.upper() ] if name.lower() in env: return env[ name.lower() ] if name in env: return env[ name ] return None def valid_decimal( decarg ): """ function valid_decimal purpose non-exception test if given value can be decimal.Decimal """ try: result = Decimal( decarg ) except InvalidOperation: result = None return result def unmod(n,m): """ function unmod purpose Return the remainder after subtracting the modulus note If a list or tuple of numbers is given, return in kind arguments 1 (num) number 2 (num) modulus returns (num) number - (number % modulus) example unmod(456789,1000) -> 456000 unmod(256,15) -> 240 usage unmod(seconds,3600) -> start of this hour in seconds unmod(seconds,86400) -> start of this day in seconds unmod(minutes,1440) -> start of this day in minutes """ if not isinstance( m, Number ): raise TypeError('Not a number passed to unmod() arg2: %s (modulus)' % repr(m)) if isinstance( n, (tuple,list) ): ns = [unmod(x,m) for x in n] if type(n) in (tuple,): return tuple(ns) return ns if not isinstance( n, Number ): raise TypeError('Not a number passed to unmod() arg1: %s (value)' % repr(n)) if m == 0: raise ValueError('Zero passed to unmod() arg2 (modulus)') if m < 0: raise ValueError('Negative value passed to unmod() arg2: %s (modulus)' % repr(m)) return n - (n % m) def find_unicode(u,notfound=-1): """ function find_unicode purpose In a unicode string, find the position of the first character that requires the unicode type and cannot be represented in mere string type. returns (int) position or the value specified by notfound= """ l = len(u) for n in xrange(l): if ord(u[n]) > 127: return n return notfound def scale( new1, new2, old1, old2, value ): """ function scale purpose Change the scale of a given number arguments 1 (num) the beginning of the new scale 2 (num) the ending of the new scale 3 (num) the beginning of the old scale 4 (num) the ending of the old scale 5 (num or tuple/list/dict of nums) value(s) to be rescaled returns (like arg 5) rescaled value(s) or None """ delta = old2 - old1 if isinstance( value, tuple): t = () for v in value: t = t + ( ( (new2 - new1) * (v - old1) + (new1 * delta) ) / delta, ) return t if isinstance( value, (list,tuple) ): l = [] for v in value: l += [ ( (new2 - new1) * (v - old1) + (new1 * delta) ) / delta ] return l if isinstance( value, dict ): d = {} for k in value.keys(): d[k] = ( (new2 - new1) * (value[k] - old1) + (new1 * delta) ) / delta return d if isinstance( value, Number ): return ( (new2 - new1) * (value - old1) + (new1 * delta) ) / delta return None def plural( value, one='', not_one='s' ): """ function plural purpose Syntactic sugar to yield 's' for plural cases else '' and allow substituting other strings. usage print( 'I see %d thing%s here'%(n,plural(n)) ) print( 'il y a %d chose%s ici'%(n,plural(n)) ) print( 'Det er %d element%s her'%(n,plural(n,'','er')) ) print( 'There %s %d thing%s here'%(plural(n,'is','are'),n,plural(n)) ) """ return one if value==1 else not_one def yes_or_no(x,no=False,yes=True,unknown=None): """ function yes_or_no aliases oui_ou_non, ja_oder_nein, ja_of_nee, ja_eller_nej, ja_eller_nei purpose Determine if a given string means yes/true or no/false arguments 1: the string or value to check no= alternate value to return for no yes= alternate value to return for yes unknown= alternate value to return for unknown returns False or no= if string/value indicates no/false True or yes= if string/value indicates yes/true None or unknwon= if string/value cannot be determined note Only a few European languages are represented here. """ if x == None: return unknown if isinstance( x, Number ): # isnum also matches bool if x: return yes else: return no elif isinstance( x, str ): if x.lower() in __nf__: return no elif x.lower() in __yt__: return yes return unknown oui_ou_non = yes_or_no ja_oder_nein = yes_or_no ja_of_nee = yes_or_no ja_eller_nej = yes_or_no ja_eller_nei = yes_or_no def test_pyutils( args ): """ function test_pyutils purpose perform tests of functions in this module with results output to stdout """ alpha = '0123456789abcdefghijklmnopqrstuvwxyz' tprint( '\nTesting scale' ) for c in (-40,0,10,15.20,25,100 ): f = scale( 32,212,0,100, c ) c = scale( 0,100,32,212, f ) tprint( str(f)+'F', '==', str(c)+'C') tprint( '\nTesting plural' ) for n in (1,2,3): tprint( '' ) tprint( 'Il y a %d chose%s ici'%(n,plural(n)) ) tprint( 'Det er %d element%s her'%(n,plural(n,'','er')) ) tprint( 'There %s %d thing%s here'%(plural(n,'is','are'),n,plural(n)) ) tprint( '\nTesting oui_ou_non' ) for f in ('oui','non','yes','no','True','False','None','unknown',True,False,None,-1,0,1,2): if oui_ou_non( f ): e = True else: e = False tprint( 'for', repr(f), 'the result is', repr(e) ) tprint( '' ) for x in range(0,12): print(x,repr(list(chunk(alpha,x)))) for x in (18,36,99,0,-1,-2,-3): print(x,repr(list(chunk(alpha,x)))) tprint( '' ) return 0 def main( args ): """main""" return test_pyutils( args ) if __name__ == '__main__': result = main( argv ) stdout.flush() try: exit( int( result ) ) except ValueError: print( str( result ), file=stderr ) exit( 1 ) except TypeError: if result == None: exit( 0 ) exit( 255 ) # EOF
link (new code)
Tradition is peer pressure from dead people
What do you call someone who speaks three languages? Trilingual. Two languages? Bilingual. One language? American.
What do you call someone who speaks three languages? Trilingual. Two languages? Bilingual. One language? American.
Reply