update_copyright_date#
Update the copyright date in all (project) text files.
Show the updated copyright ynotices in the murky package:
update_copyright_date -dv /path/to/source/murky "Pete R. Jemian"
Make the changes:
update_copyright_date -v /path/to/source/murky "Pete R. Jemian"
Motivation#
A software project under active development and maintenance should edit its copyright notice annually to include (or extend) to the current year. This task is often neglected as a project matures when the number of files to be updated increases. Sometimes, the copyright notice in some files is missed.
How does it work?#
The code looks through all text files for lines with a copyright notice. The search is independent of upper or lower case. Consider these examples:
# Copyright (C) 1988-2020 Free Software Foundation, Inc.
Copyright (C) 2008-2022 NeXus International Advisory Committee (NIAC)
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
# Copyright (c) 2006, 2008 Junio C Hamano
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
copyright = "(c) 2014-2024, Project Copyright Owner"
Copyright 2015 Jane Doe
Copyright (c) 1215, 1871, 1973, 1975-1991, 2024 Some Project Owner
The code edits the list or range of years to include the current year. For example, when run in 2024, the years in these examples are:
before |
after |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Copyright notices share a common format. [1]
Generally, a copyright notice will read something like “Copyright 2015 Jane Doe.”
The list or range of years is identified by matching common text before and
after the text that describes the years. It is common that the text before
the years is the text representation of the copyright symbol ("(C)"). The
text after the years is the name of the copyright owner. The years are four
digit numbers.
Example#
Consider a file with this copyright notice:
Copyright (c) 1215, 1871, 1973, 1975-1991 Some Project Owner
In 2024, executing command:
update_copyright_date.py -s "(c)" . Owner
updates the years in the copyright notice to:
Copyright (c) 1215, 1871, 1973, 1975-1991, 2024 Some Project Owner
Note
This is a comparable bash shell command to find (but not replace) all matching lines:
Command Positional Arguments#
root_dirDirectory with the text files with copyrights to be updated. A value of
.means the current directory. The value can be a relative path (such as.or../project) or an absolute path (such as/home/user/Documents/project/).ownerThe text to be matched that appears after the years. Typically, the name of the copyright owner.
Command Options#
Command line options may be combined as long as any parameters required by an option appear in the correct order.
-vis the same as--verbose-vvis the same as-v -vor--verbose --verbose-dvvs "(C)"is the same as--dry-run -vv --symbol "(C)"(Note that thesoption must come last since its required parameter must appear next.)
-h, --help#
Help for how to use the command-line program:
The --help option overrides any other options.
-s, --symbol#
The text to be matched that appears before the years.
The default SYMBOL is (C), common to many copyright notices.
which is equivalent to:
Quotes are necessary around the (C) to indicate to the shell that SYMBOL is
verbatim text and not a shell expansion.
To match Copyright 2015 Jane Doe, use these definitions of SYMBOL and OWNER
in the command line:
Quotes are necessary around the text Jane Doe to indicate to the shell that SYMBOL has
both words.
-y, --year#
The new year to be added. The default is the current year.
-d, --dry-run#
A dry run shows what changes will be made without modifying any files.
-v, --verbose#
Increase the level of progress messages. Warnings and errors will always be reported. Use once to add information messages. Use twice to add both information and debugging messages. More than two will be the same two.
-q, --quiet#
Do not write anything to the console, except for warnings and error messages.
This option overrides any --verbose options.
-V, --version#
Software version of this application. The --version option overrides any
other options except --help.
Source Code Documentation#
Update the copyright date in all project text files.
Finds text files in ROOT_DIR and all its subdirectories. In each file, looks
for lines that contain the pattern of SYMBOL YEARS OWNER (case-independent)
and updates YEARS to include the current year. YEARS is a list or range of
4-digit numbers.
Command Line Application
|
Entry point for command-line |
Get the command-line arguments, handle syntax errors. |
Public API
|
Return a list of all files in path and all of its subdirectories. |
|
Update the copyright year in filename. |
Internal Functions
|
Return the start and end indices of the copyright years in the text. |
|
Is the file on this path acceptable as text? |
|
Raise error if this program cannot continue, based on the inputs. |
|
Update the copyright year on this line. |
|
Set up the logging subsystem. |
|
From a list of all files, return a list of the files recognized as text. |
Separator between years in copyright notice was not expected. |
|
Did not find list or range of years in matching copyright line. |
- exception murky.update_copyright_date.UnexpectedSeparatorError#
Separator between years in copyright notice was not expected.
- exception murky.update_copyright_date.YearsNotFound#
Did not find list or range of years in matching copyright line.
- murky.update_copyright_date.command_args()#
Get the command-line arguments, handle syntax errors.
- murky.update_copyright_date.find_source_files(path)#
Return a list of all files in path and all of its subdirectories.
- murky.update_copyright_date.find_years_indices(line, symbol, owner)#
Return the start and end indices of the copyright years in the text.
- murky.update_copyright_date.is_recognized_text_file(path)#
Is the file on this path acceptable as text?
- murky.update_copyright_date.main()#
Entry point for command-line
update_copyright_dateapplication.source directory named as command line argument
target directory is specified (or defaults to present working directory)
- murky.update_copyright_date.qualify_inputs(root_path)#
Raise error if this program cannot continue, based on the inputs.
- murky.update_copyright_date.revise_copyright_line(line, symbol, owner, year)#
Update the copyright year on this line.
PARAMETERS
- linestr
Line of text that contains a copyright notice.
- symbolstr
The text to be found before the text with the years.
- ownerstr
The text to be found after the text with the years.
- yearstr
Line of text that contains a copyright notice.
- murky.update_copyright_date.setup_logging(verbosity)#
Set up the logging subsystem.
- murky.update_copyright_date.sift_file_list(file_list)#
From a list of all files, return a list of the files recognized as text.
- murky.update_copyright_date.update(filename, owner, symbol='(C)', dry_run=False, year='2024')#
Update the copyright year in filename.