a99 package

Submodules

a99.astropyaux module

a99.astropyaux.overwrite_fits(hdulist, filename)

Saves a FITS file. Combined file rename, save new, delete renamed for FITS files Why: HDUlist.writeto() does not overwrite existing files Why(2): It is also a standardized way to save FITS files

a99.config module

Gear for working with configuration files

  • subclass of configobj.ConfigObj
class a99.config.AAConfigObj(infile=None, options=None, configspec=None, encoding=None, interpolation=True, raise_errors=False, list_values=True, create_empty=False, file_error=False, stringify=True, indent_type=None, default_encoding=None, unrepr=False, write_empty_values=False, _inspec=False)

Bases: configobj.ConfigObj

Subclassed ConfigObj to create section structures automatically when getting/setting items

get_item(path_, default)

Returns item or default

Parameters:
  • -- path to item in section/subsection structure. May be either (path) – [“section”, “subsection”, …] or “[/]section/subsection/…” (leading slash is tolerated)
  • -- value to return if item is not found (default) –

Argument ‘default’ is also used to determine the type of the data to return:

  • str and list: returned as retrieved
  • int and float: eval’ed
  • bool: parsed
set_item(path_, value)

Sets item and automatically saves file

a99.config.get_config_obj(filename)

Reads/creates filename at user home folder and returns a AAConfigObj object

a99.conversion module

Conversion routines

a99.conversion.str2bool(s)

Understands “T”/”F” only (case-sensitive). To be used for file parsing.

Note This routine is limited on purpose for speed.

a99.conversion.bool2str(x)

Converts bool variable to either “T” or “F”.

Note This routine is limited on purpose for speed.

a99.conversion.chunk_string(string, length)

Splits a string into fixed-length chunks.

This function returns a generator, using a generator comprehension. The generator returns the string sliced, from 0 + a multiple of the length of the chunks, to the length of the chunks + a multiple of the length of the chunks.

Reference: http://stackoverflow.com/questions/18854620

a99.conversion.ordinal_suffix(i)

Returns ‘st’, ‘nd’, or ‘rd’.

a99.conversion.seconds2str(seconds)

Returns string such as 1h 05m 55s.

a99.conversion.make_fits_keys_dict(keys)

Returns a dictionary to translate to unique FITS header keys up to 8 characters long

This is similar to Windows making up 8-character names for filenames that are longer than this

“The keyword names may be up to 8 characters long and can only contain uppercase letters A to Z, the digits 0 to 9, the hyphen, and the underscore character.” [1]

Parameters:-- list of strings (keys) –
Returns:dictionary whose keys are the elements in the “keys” argument, and whose values are made-up uppercase names

References

[1] http://fits.gsfc.nasa.gov/fits_primer.html

a99.conversion.valid_fits_key(key)

Makes valid key for a FITS header

“The keyword names may be up to 8 characters long and can only contain uppercase letters A to Z, the digits 0 to 9, the hyphen, and the underscore character.” (http://fits.gsfc.nasa.gov/fits_primer.html)

a99.conversion.eval_fieldnames(string_, varname='fieldnames')

Evaluates string_, must evaluate to list of strings. Also converts field names to uppercase

a99.conversion.expr_to_fieldname(expr)

Keeps the rightmost part of the class name after the “_”

a99.conversion.module_to_dict(module)

Creates a dictionary whose keys are module.__all__

Returns: {“(attribute name)”: attribute, …}

a99.conversion.unicode_to_greek(s)

Converts unicode single code, e.g., ‘Σ’ to Greek letter name, e.g. ‘Sigma’

a99.conversion.greek_to_unicode(s)

Converts Greek letter name, e.g., ‘Sigma’, to unicode character, e.g. ‘Σ’

a99.conversion.make_code_readable(s)

Adds newlines at strategic places

a99.conversion.int_to_superscript(i)

int_to_superscript(i) –> str

a99.datetimefunc module

a99.datetimefunc.now_str()

a99.debugging module

a99.debugging.GetCurrentFunctionName(k=0)

Returns the function name of the caller.

Parameters:-- 1 (k=0) – caller of the caller, 2: caller of the caller of the caller etc

Obs: profiling shows that this function grabs a lot of execution time for itself.

class a99.debugging.MyLock(name=None, flag_verbose=False)

Bases: object

Lock with verbosing, helps to find deadlocks

acquire(*args)
release()

a99.fileio module

a99.fileio.rename_to_temp(filename)

Thread-safe renames file to temporary filename. Returns new name

a99.fileio.is_text_file(filepath, blocksize=8192)

Uses heuristics to guess whether the given file is text or binary, by reading a single block of bytes from the file. If more than 30% of the chars in the block are non-text, or there are NUL (‘’) bytes in the block, assume this is a binary file.

a99.fileio.multirow_str_vector(f, n, r=0)

Assembles a vector that spans several rows in a text file.

Parameters:
  • -- file-like object (f) –
  • -- number of values expected (n) –
  • r (optional) – case of error)
Returns:

(list-of-strings, number-of-rows-read-from-file)
a99.fileio.add_bits_to_path(path_, filename_prefix=None, extension=None)

Adds prefix/suffix to filename

Parameters:
  • -- path to file (path) –
  • -- prefix to be added to file name (filename_prefix) –
  • -- extension to be added to file name. The dot is automatically added, such as (extension) – “ext” and “.ext” will have the same effect

Examples

> add_bits_to_path(“/home/user/file”, “prefix-“) /home/user/prefix-file

> add_bits_to_path(“/home/user/file”, None, “.ext”) /home/user/file.ext

> add_bits_to_path(“/home/user/file”, None, “ext”) # dot in extension is optional /home/user/file.ext

> add_bits_to_path(“/home/user/”, None, “.ext”) /home/user/.ext

a99.fileio.crunch_dir(name, n=50)

Puts “…” in the middle of a directory name if lengh > n.

a99.fileio.slugify(string)

Removes non-alpha characters, and converts spaces to hyphens. Useful for making file names.

Source: http://stackoverflow.com/questions/5574042/string-slugification-in-python

a99.fileio.write_lf(h, s)

Adds lf to end of string and writes it to file.

a99.fileio.int_vector(f)

Reads next line of file and makes it a vector of floats.

a99.fileio.float_vector(f)

Reads next line of file and makes it a vector of floats.

a99.fileio.get_path(*args, module=<module 'a99' from '/home/j/Documents/projects/a99/code/a99/__init__.py'>)

Returns full path to specified module

Parameters:
  • *args – are added at the end of module path with os.path.join()
  • module – Python module, defaults to a99

Returns: path string

>>> get_path()
a99.fileio.str_vector(f)

Reads next line of file and makes it a vector of strings

Note that each str.split() already strips each resulting string of any whitespaces.

a99.fileio.new_filename(prefix, extension=None, flag_minimal=True)

returns a file name that does not exist yet, e.g. prefix.0001.extension

Parameters:
  • prefix –
  • extension – examples: “dat”, “.dat” (leading dot will be detected, does not repeat dot in name)
  • flag_minimal –
    • True: will try to be as “clean” as possible
    • False: will generate filenames in a simple, same-length pattern

Example: new_filename("molecules-", "dat", True)

In the example above, the first attempt will be “molecules.dat”, then “molecules-0000.dat”. If flag_minimal were True, it would skip the first attempt.

a99.fileio.readline_strip(f)

Reads next line of file and strips the newline.

Creates symbolic link for either operating system.

http://stackoverflow.com/questions/6260149/os-symlink-support-in-windows

a99.fileio.which(program)

Mimics UNIX ‘which’ command: return full path to executable file

http://stackoverflow.com/questions/377017/test-if-executable-exists-in-python

a99.introspection module

Routines that somehow look into the package itself

a99.introspection.import_module(filename)

Returns module object

Source: https://www.blog.pythonlibrary.org/2016/05/27/python-201-an-intro-to-importlib/

class a99.introspection.ExeInfo(filename, description, flag_error=False, flag_gui=False)

Bases: object

Information about an executable file

a99.introspection.get_exe_info(dir_, flag_protected=False)

Returns a list of ExeInfo objects, which represent Python scripts within dir_

Parameters:
  • dir – string, path to directory
  • flag_protected – whether or not to include files starting with a ‘_’
Returns:

list of ExeInfo objects

The ExeInfo objects represent the “.py” files in directory dir_,

a99.introspection.collect_doc(module, base_class=None, prefix='', flag_exclude_prefix=False)

Collects class names and docstrings in module for classes starting with prefix

Parameters:
  • -- Python module (module) –
  • -- argument for str.startswith(); if not passed, does not filter (prefix) –
  • -- filters only descendants of this class (base_class) –
  • -- whether or not to exclude prefix from class name in result (flag_exclude_prefix) –

Returns: [(classname0, signature, docstring0), …]

a99.introspection.get_classes_in_module(module, superclass=<class 'object'>)

Returns a list with all classes in module that descend from parent

Parameters:
  • module – builtins.module
  • superclass – a class

Returns: list

a99.introspection.get_obj_doc0(obj, alt='(no doc)')

Returns first line of cls.__doc__, or alternative text

a99.introspection.get_subpackages_names(dir_)

Figures out the names of the subpackages of a package

Parameters:dir – (str) path to package directory

Source: http://stackoverflow.com/questions/832004/python-finding-all-packages-inside-a-package

a99.litedb module

A holed layer over the sqlite3 API

a99.litedb.get_conn(filename)

Returns new sqlite3.Connection object with _dict_factory() as row factory

a99.litedb.conn_is_open(conn)

Tests sqlite3 connection, returns T/F

a99.litedb.cursor_to_data_header(cursor)

Fetches all rows from query (“cursor”) and returns a pair (data, header)

Returns: (data, header), where
  • data is a [num_rows]x[num_cols] list of lists;
  • header is a [num_cols] list containing the field names
a99.litedb.cursor_to_rows(cursor)

Fetches all rows from query (“cursor”) and returns a list of MyDBRow objects

class a99.litedb.MyDBRow

Bases: collections.OrderedDict

Dict subclass that allows attribute-like access of values using keys

None_to_zero()

Replace None with zero

class a99.litedb.TableInfo

Bases: collections.OrderedDict

Represents the information about a table in dict-like form where key is the field name

find(**kwargs)

Finds row matching specific field value

Parameters:**kwargs – (only one argument accepted) fielname=value, e.g., formula=”OH”

Returns: list element or None

a99.litedb.get_table_names(conn)
a99.litedb.get_table_info(conn, tablename)

Returns TableInfo object

a99.loggingaux module

Logging routines

a99.loggingaux.get_python_logger()

Returns logger to receive Python messages (as opposed to Fortran).

Note: we don’t want this to be called at any module imports, in order to give the API user a
chance to set a99.flag_log_file and a99.flag_log_console
a99.loggingaux.add_file_handler(logger, logFilename=None)

Adds file handler to logger.

File is opened in “a” mode (append)

class a99.loggingaux.LogTwo(filename)

Bases: object

Logs messages to both stdout and file.

close()
write(message)
class a99.loggingaux.SmartFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: argparse.RawDescriptionHelpFormatter

Help formatter that will show default option values and also respect newlines in description. Neither are done in default help formatter.

a99.loggingaux.str_exc(E)

Generates a string from an Exception

a99.matplotlibaux module

Matplotlib-related routines

a99.matplotlibaux.set_facecolor_white()
a99.matplotlibaux.format_BLB()

Sets some formatting options in Matplotlib.

a99.matplotlibaux.format_legend(leg)

Sets some formatting options in a matplotlib legend object.

a99.matplotlibaux.set_figure_size(fig, width, height)

Sets MatPlotLib figure width and height in pixels

Reference: https://github.com/matplotlib/matplotlib/issues/2305/

a99.matplotlibaux.remove_line(line2D)

Removes line from matplotlib plot. # http://stackoverflow.com/questions/4981815/how-to-remove-lines-in-a-matplotlib-plot

a99.misc module

Miscellanea of miscellanea

a99.misc.random_name(num_surnames=2)

Returns a random person name

Parameters:-- number of surnames (num_surnames) –

a99.parts module

Class & metaclass stuff

class a99.parts.AttrsPart

Bases: a99.parts._AAObject

Implements a new __str__() to print selected attributes.

Subclassing:
  • set the attrs class variable
attrs = None
less_attrs = None
one_liner_str()

Returns string (supposed to be) shorter than str() and not contain newline

to_dict()

Returns OrderedDict whose keys are self.attrs

to_list()

Returns list containing values of attributes listed in self.attrs

a99.parts.froze_it(cls)

Decorator to prevent from creating attributes in the object ouside __init__().

This decorator must be applied to the final class (doesn’t work if a decorated class is inherited).

Yoann’s answer at http://stackoverflow.com/questions/3603502

class a99.parts.keydefaultdict

Bases: collections.defaultdict

Subclass of defaultdict to pass the missing key to the default factory

Usage:

d = keydefaultdict(C) d[x] # returns C(x)

Source: solution by Rochen Ritzel at https://stackoverflow.com/questions/2912231/is-there-a-clever-way-to-pass-the-key-to-defaultdicts-default-factory

a99.search module

Search tools

a99.search.index_nearest(array, value)

Finds index of nearest value in array.

Parameters:
  • array – numpy array
  • value –
Returns:

int

http://stackoverflow.com/questions/2566412/find-nearest-value-in-numpy-array

a99.search.BSearch(a, x, lo=0, hi=None)

Returns index of x in a, or -1 if x not in a.

Parameters:
  • -- ordered numeric sequence (a) –
  • -- element to search within a (x) –
  • -- lowest index to consider in search* (lo) –
  • -- highest index to consider in search* (hi) –

*bisect.bisect_left capability that we don’t need to loose.

a99.search.BSearchRound(a, x, lo=0, hi=None)

Returns index of a that is closest to x.

Parameters:
  • -- ordered numeric sequence (a) –
  • -- element to search within a (x) –
  • -- lowest index to consider in search* (lo) –
  • -- highest index to consider in search* (hi) –

*bisect.bisect_left capability that we don’t need to loose.

a99.search.BSearchCeil(a, x, lo=0, hi=None)

Returns lowest i such as a[i] >= x, or -1 if x > all elements in a

So, if x is in between two elements in a, this function will return the index of the higher element, hence “Ceil”.

Parameters:
  • -- ordered numeric sequence (a) –
  • -- element to search within a (x) –
  • -- lowest index to consider in search (lo) –
  • -- highest index to consider in search (hi) –
a99.search.BSearchFloor(a, x, lo=0, hi=None)

Returns highest i such as a[i] <= x, or -1 if x < all elements in a

So, if x is in between two elements in a, this function will return the index of the lower element, hence “Floor”.

Parameters:
  • -- ordered numeric sequence (a) –
  • -- element to search within a (x) –
  • -- lowest index to consider in search (lo) –
  • -- highest index to consider in search (hi) –
a99.search.FindNotNaNBackwards(x, i)

Returns last position (starting at i backwards) which is not NaN, or -1.

a99.textinterface module

a99.textinterface.format_h1(s, format='text', indents=0)

Encloses string in format text

Parameters:
  • s – string
  • intents – number of leading intenting spaces
  • format – string starting with “text”, “markdown”, or “rest”

Returns: list

>>> print("\n".join(format_h2("Header 1", indents=10)))
          Header 1
          --------

>>> print("\n".join(format_h2("Header 1", "markdown", 0)))
## Header 1
a99.textinterface.format_h2(s, format='text', indents=0)

Encloses string in format text

Parameters:
  • s – string
  • format – string starting with “text” or “markdown”
  • intents – number of leading intenting spaces

Returns: list

>>> print("\n".join(format_h2("Header 2", indents=2)))
  Header 2
  --------

>>> print("\n".join(format_h2("Header 2", "markdown", 2)))
## Header 2
a99.textinterface.fmt_error(s)

Standardized embellishment. Adds formatting to error message.

a99.textinterface.print_error(s)

Prints string as error message.

a99.textinterface.menu(title, options, cancel_label='Cancel', flag_allow_empty=False, flag_cancel=True, ch='.')

Text menu.

Parameters:
  • -- menu title, to appear at the top (title) –
  • -- sequence of strings (options) –
  • -- label to show at last "zero" option (cancel_label='Cancel') –
  • -- Whether to allow empty option (flag_allow_empty=0) –
  • -- whether there is a "0 - Cancel" option (flag_cancel=True) –
  • -- character to use to draw frame around title (ch=".") –
Returns:

None; 0-Back/Cancel/etc; 1, 2, …
Return type:

option – an integer

Adapted from irootlab menu.m

a99.textinterface.format_progress(i, n)

Returns string containing a progress bar, a percentage, etc.

a99.textinterface.markdown_table(data, headers)

Creates MarkDown table. Returns list of strings

Parameters:
  • -- [ (data) –
  • -- sequence of strings (headers) – (header0, header1, …)
a99.textinterface.format_exe_info(exeinfo, format='text', indlevel=0)

Generates listing of all Python scripts available as command-line programs.

Args:

exeinfo – list of ExeInfo objects

format – One of the options below:
“text” – generates plain text for printing at the console “markdown-list” – generates MarkDown as list “markdown-table” – generates MarkDown as tables “rest-list” – generates reStructuredText as lists

indents – indentation level (“text” format only)

Returns: (list of strings, maximum filename size)
list of strings – can be joined with a “
“
maximum filename size
a99.textinterface.format_box(title, ch='*')

Encloses title in a box. Result is a list

>>> for line in format_box("Today's TODO list"):
...     print(line)
*************************
*** Today's TODO list ***
*************************
a99.textinterface.yesno(question, default=None)

Asks a yes/no question

Parameters:
  • question – string without the question mark and without the options. Example: ‘Create links’
  • default – default option. Accepted values are ‘Y’, ‘YES’, ‘N’, ‘NO’ or lowercase versions of these valus (this argument is case-insensitive)
Returns:

True if user answered Yes, False otherwise
Return type:

bool
a99.textinterface.rest_table(data, headers)

Creates reStructuredText table (grid format), allowing for multiline cells

Parameters:
  • -- [ (data) –
  • -- sequence of strings (headers) – (header0, header1, …)

Note Tolerant to non-strings

Note Cells may or may not be multiline

>>> rest_table([["Eric", "Idle"], ["Graham", "Chapman"], ["Terry", "Gilliam"]], ["Name", "Surname"])
a99.textinterface.expand_multirow_data(data)

Converts multirow cells to a list of lists and informs the number of lines of each row.

Returns:new_data, row_heights
Return type:tuple

Module contents