losalamos.notes#

Utilities for managing structured Markdown notes.

This module provides a lightweight framework for creating, loading, and managing Markdown-based notes with structured metadata. It supports templated note creation, automated refactoring of note names and links, reference notes with BibTeX integration, and utilities for working with collections of notes.

Quick start#

This section demonstrates common operations for working with Markdown-based notes.

Load a note

from losalamos.notes import Note

note = Note(name="Example", alias="Nt1")
note.load("path/to/note.md")

print(note.metadata)
print(note.data)

Create a new note from a template

from losalamos.notes import NoteBasic

note = NoteBasic()
note.load_new("path/to/new_note.md")

note.metadata["abstract"] = '"Short description of the note."'
note.update()
note.save()

Refactor a note and update links

from losalamos.notes import Note

note = Note()
note.load("path/to/old_name.md")

note.refactor(
    new_name="new_name",
    scope="path/to/notes_folder"
)

Create a reference note

from losalamos.notes import NoteReference

note = NoteReference()

metadata = {
    "entry_type": "article",
    "name": "smith2022",
    "author": "Smith, John and Doe, Jane",
    "title": "Example Article",
    "year": "2022",
    "journal": "Journal of Examples",
    "doi": "10.1000/example"
}

note.load_new(
    file_note="path/to/smith2022.md",
    metadata=metadata
)

note.save()

Export BibTeX from a reference note

from losalamos.notes import NoteReference

note = NoteReference()
note.load("path/to/smith2022.md")

note.to_bib("path/to/file.bib")

Load a collection of notes

from losalamos.notes import NoteCollection

coll = NoteCollection()

coll.load_folder("path/to/notes")

print(len(coll))

Search notes using a glob pattern

from losalamos.notes import NoteCollection

coll = NoteCollection()

coll.load_pattern("path/to/notes/**/*.md")

for note in coll:
    print(note.name)

Functions

search_markdown_files(paths)

Recursively scans the provided paths to identify and collect all files with a .md extension.

Classes

`Note`([name, alias])
`NoteBasic`([name, alias])
`NoteCollBasic`([name, alias])
`NoteCollFigure`([name, alias])
`NoteCollJournal`([name, alias])
`NoteCollProject`([name, alias])
`NoteCollection`([name, alias])
`NoteDataset`()
`NoteFigure`([name, alias])
`NoteJournal`([name, alias])
`NoteProject`([name, alias])
`NoteReference`()

losalamos.notes.search_markdown_files(paths: list[Path]) → list[Path][source]#

Recursively scans the provided paths to identify and collect all files with a .md extension.

Parameters:: paths (list[pathlib.Path]) – A list of file or directory paths to search.
Returns:: A list of paths pointing to the discovered markdown files.
Return type:: list[pathlib.Path]

class losalamos.notes.Note(name='MyNote', alias='Nt1')[source]#

Bases: MbaE

STR_HEAD = 'Head'#

STR_BODY = 'Body'#

STR_TAIL = 'Tail'#

get_metadata()[source]#: This method returns all objects metadata, incluiding selected attributes beyond the metadata of the file

load_metadata(file_note=None)[source]#

setup_metadata(metadata)[source]#

load_data(file_note=None)[source]#

load(file_note=None)[source]#

save()[source]#: Save object resources to sourced files.

Danger

This method overwrites the sourced data file.

export(folder, filename, export_metadata=False)[source]#

Export to a markdown file with optional metadata handling.

Parameters:

folder (str) – The directory path where the file will be saved.
filename (str) – The name of the file without the extension.
export_metadata (bool) – Toggle to trigger the parent class metadata export. Default value = False

Returns:

Path to the exported file

Return type:

Path

Note

This method constructs a file path using pathlib.Path and appends the .md extension. It calls the internal to_file method with cleanup enabled to finalize the document. If export_metadata is set to True, it invokes the export method of the superclass before proceeding.

to_file(file_path, cleanup=True)[source]#

Write the note object’s metadata and data content to a specified file.

Parameters:

file_path (str) – The destination path where the note will be written.
cleanup (bool) – Toggle to remove excessive blank lines after writing. Default value = True

Returns:

None

Return type:

NoneType

Note

This method aggregates metadata and data by calling metadata_to_list and data_to_list. It sanitizes the output by replacing None string occurrences with empty strings and ensures each entry ends with a newline character. If cleanup is enabled, it post-processes the file using remove_excessive_blank_lines to maintain consistent formatting.

refactor(new_name, scope)[source]#

Renames the current file note and updates all internal markdown links within a specified scope.

Note

This function performs a regex-based search across the provided scope to find and replace Obsidian-style internal links (e.g., [[OldName]] or [[OldName|Alias]]) with the newly defined name.

Parameters:

new_name (str) – The new filename (without extension) to be applied.
scope (pathlib.Path, str, or Iterable) – The directories or file paths where link references should be updated.

Returns:

None

Return type:

None

static harmonize_entry_text(entry)[source]#

static harmonize_entry_date(entry, key='date')[source]#

static harmonize_entry_date_old(entry, key='date')[source]#

static remove_excessive_blank_lines(file_path)[source]#

Remove consecutive blank lines from a file to ensure only single blank lines remain.

Parameters:: file_path (str) – The path to the target text file to be processed.
Returns:: None
Return type:: NoneType

Note

This method performs an in-place modification of the file. It iterates through the content and suppresses any sequence of empty lines that exceeds a single occurrence, effectively “squeezing” the vertical whitespace.

static parse_metadata(note_file)[source]#

Extracts YAML metadata from the header of a Markdown file.

Parameters:: note_file – str, path to the Markdown file
Returns:: dict, extracted YAML metadata

static parse_yaml(yaml_content)[source]#

Parses YAML content into a dictionary.

Parameters:: yaml_content – str, YAML content as string
Returns:: dict, parsed YAML content

static metadata_to_list(metadata_dict)[source]#

Convert a dictionary of metadata into a formatted list of strings.

Parameters:: metadata_dict (dict) – A dictionary containing metadata keys and values to be formatted.
Returns:: A list of strings formatted with YAML-like syntax, enclosed by dashed separators.
Return type:: list

Note

The method processes dictionary entries into a human-readable list format. It handles list values by creating indented bullet points and converts None values into empty strings. The resulting list starts and ends with a --- delimiter string.

static data_to_list(data_dict)[source]#

Flatten a dictionary of lists into a single list separated by blank lines and delimiters.

Parameters:: data_dict (dict) – A dictionary where each key maps to a list of strings to be aggregated.
Returns:: A concatenated list of all values with added structural spacing and separators.
Return type:: list

Note

This function iterates through the top-level keys of data_dict and appends the contents of each list to a master list. After each group of data, it inserts an empty string, a --- separator, and another empty string to visually distinguish different levels or sections.

static parse_note(file_path)[source]#

Extract and categorize note content into head, body, and tail sections based on separators.

Parameters:: file_path (str) – The path to the note file to be parsed.
Returns:: A dictionary containing the cleaned lines for Head, Body, and Tail.
Return type:: dict

Note

The function first identifies and skips an initial YAML frontmatter block if it starts with ---. It then uses the --- string as a delimiter to segment the remaining text. If multiple separators exist, the first and last act as boundaries for the Body, while everything before the first is Head and everything after the last is Tail. All extracted lines undergo a strip() operation to remove leading/trailing whitespace.

static list_by_pattern(md_dict, patt_type='tag')[source]#

Retrieve a list of patterns from the note dictionary.

Parameters:

md_dict (dict) – Dictionary containing note sections.
patt_type (str) – Type of pattern to search for, either “tag” or “related”. Defaults to “tag”.

Returns:

List of found patterns or None if no patterns are found.

Return type:

list or None

class losalamos.notes.NoteBasic(name='MyNote', alias='Nt1')[source]#

Bases: Note

TEMPLATE_FILE = PosixPath('/home/runner/work/losalamos/losalamos/src/losalamos/data/templates/notes/_basic.md')#

THUMBNAIL_SIZE = None#

PATTERN_ABSTRACT = '[!Abstract]'#

classmethod get_template_file()[source]#

Retrieves the filesystem path of the template file associated with the class.

Returns:: The path to the template file.
Return type:: pathlib.Path

load_new(file_note)[source]#

Initializes a new note instance using a template and assigns it a new file path.

Parameters:: file_note (str or pathlib.Path) – The destination path where the new note will be saved.

load_data_standard()[source]#

Parses and returns the standard data content from the template file.

Returns:: A dictionary containing the parsed data from the template.
Return type:: dict

load_metadata_standard()[source]#

Retrieves the metadata structure from the template and initializes all values to None.

Returns:: A dictionary of metadata keys with cleared values.
Return type:: dict

load_metadata(file_note=None)[source]#

Loads metadata and synchronizes it against the standard template schema.

Important

This method filters the current metadata to ensure only keys present in metadata_standard are kept, filling missing keys with None.

Returns:: No value is returned.
Return type:: None

reset_data()[source]#: Resets all data segments including Head, Body and Tail to their standard values.

Danger

This action will erase all current data in the instance.

reset_data_segment(segment)[source]#

Resets a specific data segment to its standard default state.

Parameters:: segment (str) – The name of the data segment to reset (e.g., Head, Body, or Tail).

Danger

This action will erase the current data for the specified segment.

reset_data_head()[source]#: Resets the Head data segment to its standard default state.

Danger

This action will erase the current data segment.

reset_data_body()[source]#: Resets the Body data segment to its standard default state.

Danger

This action will erase the current data segment.

reset_data_tail()[source]#: Resets the Tail data segment to its standard default state.

Danger

This action will erase the current data segment.

refactor(new_name, scope)[source]#

Performs a full refactor operation by renaming the resource and refreshing its local data state.

Parameters:

new_name (str) – The new filename to be assigned to the resource.
scope (pathlib.Path, str, or Iterable) – The scope of files where references to this resource should be updated.

Returns:

None

Return type:

None

update()[source]#: Triggers a sequence of internal updates to synchronize the note’s name, abstract, and thumbnail.

Note

This method acts as a base update sequence; additional update logic may be implemented in downstream classes.

update_name()[source]#: Updates the note metadata and the first line of the Head segment with the current file stem.

Warning

This method assumes the first item in the Head data segment is the title and will overwrite it.

update_abstract()[source]#: Synchronizes the abstract from metadata into the Head data segment block.

Note

The method searches for the self.PATTERN_ABSTRACT identifier within the Head segment and replaces the subsequent line with the formatted abstract string.

update_thumbnail(image_name=None)[source]#: Updates the thumbnail image link in the Head data segment based on the current file name and predefined size.

Note

The method searches for an existing Wikilink image pattern (![[) within the Head segment to perform the replacement.

update_timestamp()[source]#: Records the current local date and time into the note metadata.

Note

The timestamp is formatted as a string following the %Y-%m-%d %H:%M:%S pattern.

update_note(file_note=None)[source]#

class losalamos.notes.NoteProject(name='MyNote', alias='Nt1')[source]#

Bases: NoteBasic

TEMPLATE_FILE = PosixPath('/home/runner/work/losalamos/losalamos/src/losalamos/data/templates/notes/_project.md')#

THUMBNAIL_SIZE = None#

class losalamos.notes.NoteJournal(name='MyNote', alias='Nt1')[source]#

Bases: NoteBasic

TEMPLATE_FILE = PosixPath('/home/runner/work/losalamos/losalamos/src/losalamos/data/templates/notes/_journal.md')#

THUMBNAIL_SIZE = 300#

update()[source]#: Triggers a sequence of internal updates to synchronize the note’s name, abstract, and thumbnail.

Note

This method acts as a base update sequence; additional update logic may be implemented in downstream classes.

update_title()[source]#

class losalamos.notes.NoteFigure(name='MyNote', alias='Nt1')[source]#

Bases: NoteBasic

TEMPLATE_FILE = PosixPath('/home/runner/work/losalamos/losalamos/src/losalamos/data/templates/notes/_figure.md')#

THUMBNAIL_SIZE = 500#

class losalamos.notes.NoteReference[source]#

Bases: NoteBasic

TEMPLATE_FILE = PosixPath('/home/runner/work/losalamos/losalamos/src/losalamos/data/templates/notes/_reference.md')#

THUMBNAIL_SIZE = 200#

PATTERN_ABSTRACT = '[!Info]'#

get_reference()[source]#

Creates and returns a standardized Reference object based on the current metadata.

Returns:: A reference instance populated with standardized internal metadata.
Return type:: Reference

get_str_bib(drop_fields=None)[source]#

Generates a BibTeX string representation of the reference with an option to exclude specific fields.

Parameters:: drop_fields (list) – [optional] A list of metadata keys to remove before generating the string.
Returns:: The formatted BibTeX string.
Return type:: str

load_new(file_note, metadata=None)[source]#

Initializes a new note from a file and optionally sets and updates its metadata.

Parameters:

file_note (str | pathlib.Path) – The path or identifier for the note file.
metadata (dict) – [optional] A dictionary of metadata to apply to the new note.

Returns:

No value is returned.

Return type:

None

update()[source]#

Triggers a comprehensive refresh of all derived metadata, citation strings, and document sections.

Returns:: No value is returned.
Return type:: None

update_cite_inline()[source]#

Updates the inline citation string in the metadata using the plain text format.

Returns:: No value is returned.
Return type:: None

update_cite_bibli()[source]#

Updates the bibliographic citation string in the metadata according to the defined style.

Returns:: No value is returned.
Return type:: None

update_pdf()[source]#

Formats and updates the PDF link field in the metadata based on the entry name.

Returns:: No value is returned.
Return type:: None

update_data_head()[source]#

Refreshes the header section of the document data, specifically handling journal links for articles.

Returns:: No value is returned.
Return type:: None

update_data_tail()[source]#

Refreshes the tail section of the document by injecting formatted metadata and BibTeX strings.

Note

This method synchronizes the end-of-file data by generating a clean BibTeX entry (excluding bloat like PDFs or abstracts) and performing string interpolation on the STR_TAIL template list using the current metadata dictionary.

Returns:: No value is returned.
Return type:: None

update_thumbnail(image_name=None)[source]#

Updates the document thumbnail, automatically selecting the journal name as the image source for articles.

Parameters:: image_name (str) – [optional] The specific image name or key to use for the thumbnail.
Returns:: No value is returned.
Return type:: None

to_bib(output, drop_pdf=True)[source]#

Exports the reference metadata to a BibTeX file with an option to exclude the PDF field.

Parameters:

output (str | pathlib.Path) – The file path or buffer where the BibTeX data should be saved.
drop_pdf (bool) – Whether to remove the pdf field from the exported file. Default value = True

Returns:

No value is returned.

Return type:

None

class losalamos.notes.NoteDataset[source]#

Bases: NoteReference

TEMPLATE_FILE = PosixPath('/home/runner/work/losalamos/losalamos/src/losalamos/data/templates/notes/_dataset.md')#

THUMBNAIL_SIZE = 200#

PATTERN_ABSTRACT = '[!Info]'#

update()[source]#

Triggers a comprehensive refresh of all derived metadata, citation strings, and document sections.

Returns:: No value is returned.
Return type:: None

to_bib(output)[source]#

Exports the reference metadata to a BibTeX file with an option to exclude the PDF field.

Parameters:

output (str | pathlib.Path) – The file path or buffer where the BibTeX data should be saved.
drop_pdf (bool) – Whether to remove the pdf field from the exported file. Default value = True

Returns:

No value is returned.

Return type:

None

update_pdf()[source]#

Formats and updates the PDF link field in the metadata based on the entry name.

Returns:: No value is returned.
Return type:: None

update_source()[source]#

update_alias()[source]#

update_version()[source]#

get_dataset_folder(folder_base)[source]#

setup_dataset_folder(folder_base)[source]#

class losalamos.notes.NoteCollection(name='MyNoteColl', alias='NtCol0')[source]#

Bases: Collection

BASE_OBJECT#: alias of Note

load_list(files)[source]#

Iterates through a list of file paths to initialize, load, and append objects to the collection.

Parameters:: files (list) – A list of file paths to be processed.
Returns:: None
Return type:: None

load_folder(folder)[source]#

Identifies all Markdown files within a specific directory and adds them to the collection.

Parameters:: folder (str) – The directory path to scan for .md files.
Returns:: None
Return type:: None

load_pattern(pattern)[source]#

Uses a glob pattern to locate files and load them into the collection.

Parameters:: pattern (str) – The search pattern (e.g., path/to/*/*.md) used to match files.
Returns:: None
Return type:: None

class losalamos.notes.NoteCollBasic(name='MyNoteColl', alias='NtCol0')[source]#

Bases: NoteCollection

BASE_OBJECT#: alias of NoteBasic

class losalamos.notes.NoteCollProject(name='MyNoteColl', alias='NtCol0')[source]#

Bases: NoteCollection

BASE_OBJECT#: alias of NoteProject

class losalamos.notes.NoteCollJournal(name='MyNoteColl', alias='NtCol0')[source]#

Bases: NoteCollection

BASE_OBJECT#: alias of NoteJournal

class losalamos.notes.NoteCollFigure(name='MyNoteColl', alias='NtCol0')[source]#

Bases: NoteCollection

BASE_OBJECT#: alias of NoteFigure

losalamos.notes#

Quick start#

This Page