Package: todonotifier
TODO NotifierDescriptionMore often than not, we put some TODO items in code and forget about them. Sometimes, we
think of coming back to a TODO item by some date but miss it being too busy with some
other development.TODO Notifier aims to solve this problem. It parses through any project, collects all
the TODO items, generates automated summaries and sends automated reminders about them.Let's first see TODO Notifier in action.Recommended format to write TODO items**TODO {2022-05-22} @user_name msgThe above format has the following componentsTODOin the capital (though users can make it case insensitive by setting the same
inconfig.py). It need not be starting word of the line. For a host of valid
examples, please checktests/sample_test_file.pyandtests/sample_test_file2.py[Optional] TODO is followed by a date inYYYY-MM-DDformat within curly brackets.
The respective TODO item is expected to be completed by the end of this date[Optional] Date is followed by a unique user name accompanied by@[Optional] User name is followed by the usual message/comment of the respective TODO
itemBut, the relative position of theTODOitem, date inside{}brackets, username with@and message should be as recommended above.The framework is robust. If the TODO item misses some data like date and/or message
and/or username etc., the respective TODO item will still be picked up by the TODO
Notifier. But, without relevant information, certain functionalities may not work. For
e.g. without a date, it cannot know if the TODO item has overshot its expected date of
completion.How to use it?Before running TODO Notifier, check out the sample summary files produced by the TODO
Notifier in the directorysample_reports. It generates three default summaries. For
more information, check out point #3 inSalient Features.Method 1: As a pip packageInstall TODO Notifier by runningpip install todonotifierThen you can use the below code to try the TODO Notifier.fromtodonotifier.configimportDefaultConfigfromtodonotifier.connectimportCONNECT_METHOD,Connectfromtodonotifier.driverimportrunasdriver_rungit_url:str=""# Placeholder for HTTPS/SSH based git url. It could also be a local folder addressproject_dir_name:str=""# Placeholder. Suggested to keep same as project namesender_email=""password=""receivers=[]host="smtp.gmail.com"# Change accordinglyport=465# Change accordinglynotifier=EmailNotifier(sender_email,password,host,port,receivers)config=DefaultConfig(save_html_reports=True,ignore_todo_case=True,notifier=notifier)# Change flags as per needconnect=Connect(connect_method=CONNECT_METHOD.GIT_CLONE,project_dir_name=project_dir_name,url=git_url,branch_name="production")# If using a local folder address in `git_url`, then change `connect_method` to `CONNECT_METHOD.DRY_RUN_DIR`driver_run(connect=connect,config=config)It will generate three files by default in folder.reportunder the current working
directory.Method 2: Directly cloning from GitHubClone usinggit clone https://github.com/ashu-tosh-kumar/todo_notifier.gitThen you can use theuser_driver.pyfile to run it. You can edit theuser_driver.pyto following to try running it ontests/sample_test_file.py.git_url:str="tests/sample_test_file.py"# Placeholder for HTTPS/SSH based git urlproject_dir_name:str=""# Placeholder. Suggested to keep same as project namesender_email=""password=""receivers=[]host="smtp.gmail.com"port=465notifier=EmailNotifier(sender_email,password,host,port,receivers)config:BaseConfig=DefaultConfig(save_html_reports=True,ignore_todo_case=True,notifier=notifier)# Change flags as per needconnect=Connect(connect_method=CONNECT_METHOD.DRY_RUN_FILE,project_dir_name=project_dir_name,url=git_url,branch_name="production")# If using a local folder address in `git_url`, then change `connect_method` to `CONNECT_METHOD.DRY_RUN_DIR`. For `CONNECT_METHOD.DRY_RUN_FILE` and `CONNECT_METHOD.DRY_RUN_DIR`, branch_name is not importantdriver_run(connect=connect,config=config)It will generate three files by default in folder.reportunder the main project
directory.This method is not recommended and there's always a risk of overriding any local changes
made when pulling the latest changes. Please use Method 1.Accessing generated summariesAfter running the above code to generate the summaries, the TODO Notifier stores these
summaries as.htmlfiles ifsave_html_reports=Trueis passed in the configuration.
All such reports are saved in the directory.reportin the current working directory.TODO Notifier also sends automated emails about the same if set up in the configuration.But, if users need access to the generated summaries for some custom downstream
integration, they can access the same as below:# Access all the summary generatorsconfig.config.summary_generators# Access summary from (say) ByModuleSummaryGeneratorby_module_summary_generator=config.summary_generators[0]# Check name of the respective summary generatorby_module_summary_generator.name# Generated `list` of `TODO` objectsby_module_summary_generator.container# Generated html summary of `TODO` objectsby_module_summary_generator.htmlTechnical DetailsWorkingTODO Notifier copies/clones the respective repository into a temporary location to
avoid the risk of modifying any file.It then reads through all the files in the project and collects all the TODO items.It then generates the summaries as specified in the configuration.Finally, it sends the notifications (only Email notifications are supported as of now)
to the configured email id.Salient FeaturesAllows excluding specific folders of the project via absolute address, relative
address or regular expression from being scanned. It has a default list of folders
that are not scanned:DEFAULT_EXCLUDE_DIRSinconstants.py. But the same can be
controlled using the flagflag_default_exclude_dirsinconfig/DefaultConfigAllows excluding specific files of the project via absolute address, relative address
or regular expression from being scanned. It has a default list of files that are not
scanned:DEFAULT_EXCLUDE_FILESinconstants.py. But the same can be controlled
using the flagflag_default_exclude_filesinconfig/DefaultConfigProvides three default summary generators. Summaries are how TODO Notifier shares
information about TODO items. Each summary is an HTML document that can be shared. The
default summary generation can be controlled by a flag:flag_default_summary_generatorsinconfig/DefaultConfig.Module-wise list of all TODO itemsUser-wise list of TODO items expired alreadyUser-wise list of TODO items that are supposed to expire in the upcoming weekFlagsave_html_reportscan be used to control whether to save the generated
summaries as files. If yes, it will store all generated summaries in folder.reportlocallyUsers can write their own summary generators and add pass the same in variablesummary_generatorsinconfig/DefaultConfig. Each summary generator is a child ofBaseSummaryGeneratorinsummary_generators.pyProvides a default implementation of sending notifications via Email asEmailNotifierinnotifications.py. More ways of notifications can be added by
inheriting fromBaseNotifierMost of the features are configurable via a configuration file. Configuration must be
a child class ofBaseConfiginconfig.py. It provides a default configuration
class:DefaultConfiginconfig.pythat can also be configured via various flag
parameters. But users are free to write another configuration class or simply inherit
fromDefaultConfigProvides two ways of dry running the code locally viz.CONNECT_METHOD.DRY_RUN_FILEto dry run on a single local file andCONNECT.DRY_RUN_DIRto dry run on an entire
local directory/project.user_driver.pyprovides an example of how to use it. It can be modified accordingly to
run the code.LinksFind the package onPyPiRead article on how to setup TODO Notifier onMediumDocumentation onGitHub Pages.