Package: logcraft
logcraftPython Macro-Generated Logging from CommentsIntroductionWhat islogcraft?logcraftgives the functionality of automatically generating logging calls from annotated comments. This treats logging as documentation, separates application logging and program flow to the highest degree, and provides an overall better development experience.Source code files are not modified. Instead the@logmacro is only applied at the decoration of your object. This gives greater transparency and control to the developer.Write This:Instead Of:@logdefdo_something(x):#i: started doing something with {x}x=do_something_interesting(x)#i: finished doing somethingreturnxdefdo_something(x):logging.info(f"started doing something with{x}")x=do_something_interesting(x)logging.info("finished doing something")returnxMoreover,logcrafthas the following benefits:No external dependenciesMacro expansion is limited to decorated objectsNo source files are modifiedWorks withpickleand other serialisation librariesInject your own logger (loguruetc.) or a custom callable to replaceprintAllows continuation over multiple commentsAllows string formatting with evaluated variablesInspired by:node-comment-macrosand conversations with@kaleand@jiaxi.Whylogcraft?A lot of logging in Python these days are simply descriptive in nature (e.g. "procedurexstarted" or "xiteration hasyvariable"). These logging calls usually adds no functionality to the program logic and clouds the programmer's interpretation of the source code.This library applies the opinion thatlogging which are documentative in nature should be treated as documentation.Hence, logging should be generated from annotated comments and logging configuration should be easily injected without modifying the program logic. Having logging as comments results in a clear delineationHow Do I Install?Simply run:pipinstalllogcraftQuickstartImport the@logdecorator:fromlogcraft.macroimportlogDecorate your object with@logand annotate comments which are intended to be logging messages. Comments with the same annotation and are right after another are treated as continuations of the same logging call. Furthermore, annotated comments with"{}"will be expanded into f-strings that references variables in the local or global namespaces.Note that@loghas to be the top decoratorThe following:@logdefadd_one(sequence):"""Adds 1 to sequence"""#: add print call with line#: continuation# this is some ignored comment#: add another line#i: this is an info message#d: this is a debug messagenew_sequence=[]forxinsequence:#d: adding 1 to x={x}new_sequence.append(x+1)#d: finished adding 1 to x={x}#i: constructed new sequence {new_sequence}returnnew_sequenceWill be expanded to:defadd_one(sequence):"""Adds 1 to sequence"""print("add print call with line continuation")# this is some ignored commentprint("add another line")logging.info("this is an info message")logging.debug("this is a debug message")new_sequence=[]forxinsequence:logging.debug(f"adding 1 to x={x}")new_sequence.append(x+1)logging.debug(f"finished adding 1 to x={x}")logging.info(f"constructed new sequence{new_sequence}")returnnew_sequenceList of AnnotationsThe following are the available list of annotations:#: callable (default: print)#c: logging.critical#d: logging.debug#e: logging.error#f: logging.fatal#i: logging.info#w: logging.warnOther Installation MethodsSourceClone the repository:gitclonehttps://github.com/ryanlyn/logcraftRun installation:cdlogcraft
pythonsetup.pyinstallLicenselogcraftis made available under the MIT License. For more details, see theLICENSE.