Logging, provenance and C libraries
Logging for GRANDlib and for the scripts that use it. |
|
Which GRANDlib produced a file: the package version and its git commit. |
|
Wrapper for the GULL C library |
|
Wrapper for the TURTLE C library |
grand.manage_log
Logging for GRANDlib and for the scripts that use it.
Library modules only create a logger and write to it; they never configure where the messages go. That is left to the script that runs them, as the Python logging guide recommends. In a library module:
from logging import getLogger
logger = getLogger(__name__)
def foo(var):
logger.debug("call foo()")
logger.info(f"var={var}")
A script chooses the output and the level with
create_output_for_logger(), and gets its own logger with
get_logger_for_script(), since __name__ is "__main__" there.
string_begin_script(), string_end_script(), chrono_start()
and chrono_string_duration() format the usual start, end and timing
lines.
Examples
A script that logs to the terminal and to log.txt at debug level:
import grand.manage_log as mlg
logger = mlg.get_logger_for_script(__file__)
mlg.create_output_for_logger("debug", log_file="log.txt", log_stdout=True)
logger.info(mlg.string_begin_script())
logger.info(mlg.chrono_start())
... # the work
logger.info(mlg.chrono_string_duration())
logger.info(mlg.string_end_script())
Each line of the log reads:
11:28:09.621 INFO [grand.sim.efield2voltage 412] message
To reuse this module in another project, change NAME_PKG_GIT and
NAME_ROOT_LIB.
- grand.manage_log.create_output_for_logger(log_level='info', log_file=None, log_stdout=True, log_root='grand')[source]
Create a logger with handler for grand
- grand.manage_log.close_output_for_logger(log_root='grand')[source]
close handler for test
- Parameters:
log_root (str, optional) – Logger whose handlers to close.
- grand.manage_log.get_logger_for_script(pfile)[source]
Return a logger with root logger is defined by the path of the file.
- @note
Must be call before create_output_for_logger()
- Parameters:
pfile (str) – Path of the calling script, used to name the logger.
- Returns:
A logger named after that script.
- Return type:
- grand.manage_log.string_begin_script()[source]
Return string start message with date, time
- Returns:
A banner marking the start of a script run.
- Return type:
- grand.manage_log.string_end_script()[source]
Return string end message with date, time and duration
- Returns:
A banner marking the end, with the elapsed time.
- Return type:
- grand.manage_log.chrono_start()[source]
Start chonometer
- Returns:
The start time, to pass to
chrono_string_duration().- Return type:
- grand.manage_log.chrono_string_duration()[source]
Return string with duration between call chrono_start()
- Returns:
Elapsed time since
chrono_start(), formatted.- Return type:
grand.provenance
Which GRANDlib produced a file: the package version and its git commit.
Every tree GRANDlib creates records this in its modification_software and
modification_software_version metadata, so a simulated or
converted file says which code wrote it. The package version alone is not
enough: it moves only on release, and most files are written from a git
checkout between releases.
- grand.provenance.SOFTWARE_NAME = 'GRANDlib'
What
modification_softwarerecords for trees GRANDlib creates.
- grand.provenance.package_version()[source]
Returns the installed GRANDlib version, or
"unknown".Read from the package metadata rather than a constant, so it cannot drift from what was installed.
"unknown"rather than an error when the package is not installed: running from a source tree is legitimate.- Return type:
- grand.provenance.git_state(root=None)[source]
Describes the git checkout GRANDlib runs from, if it runs from one.
- Parameters:
root (str, optional) – The repository to describe. Defaults to the one holding this package.
- Returns:
commit(full hash),branch("HEAD"when detached) andmodified(True when tracked files differ from the commit). None whenrootis not the top of a git checkout – for example an installed copy – so that a copy installed inside some other repository never reports that repository’s commit.- Return type:
dict or None
- grand.provenance.describe(root=None)[source]
Returns the version string written into files.
- Parameters:
root (str, optional) – Passed to
git_state().- Returns:
For example
"0.2.0 (git dev-next 1aeac037153a..., modified)", or the package version alone outside a git checkout.- Return type:
- grand.provenance.current()[source]
Returns
describe()for this package, computed once per process.Trees are created often; git runs only the first time.
- Return type:
grand.geo.gull
Wrapper for the GULL C library
- exception grand.geo.gull.LibraryError(code)[source]
Bases:
RuntimeErrorA GULL library error
grand.geo.turtle
Wrapper for the TURTLE C library
- exception grand.geo.turtle.LibraryError(code: int)[source]
Bases:
RuntimeErrorA TURTLE library error
- class grand.geo.turtle.Map(path: Path | str)[source]
Bases:
objectProxy for a TURTLE map object
- cache = {}
- class grand.geo.turtle.Stack(path: Path | str, stack_size: int = 0)[source]
Bases:
objectProxy for a TURTLE stack object
- property path
The path where the data tiles are located
- Returns:
Directory holding the elevation tiles.
- Return type:
- class grand.geo.turtle.Stepper[source]
Bases:
objectProxy for a TURTLE stepper object
- grand.geo.turtle.ecef_from_geodetic(latitude, longitude, altitude)[source]
Convert geodetic coordinates to ECEF ones
- grand.geo.turtle.ecef_from_horizontal(latitude, longitude, azimuth, elevation)[source]
Convert horizontal coordinates to an ECEF direction
- grand.geo.turtle.ecef_to_geodetic(ecef)[source]
Convert ECEF coordinates to geodetic ones
- Parameters:
ecef (array_like) – ECEF position, in meters.
- Returns:
Latitude and longitude in degrees, altitude in meters.
- Return type: