markdown.obisidian.personal.reference

Functions for managing references in an Obsidian.md math vault

import shutil
import tempfile
from unittest import mock

from fastcore.test import *

from trouver.helper import _test_directory

Getting a reference folder

---

source

index_note_for_reference

 index_note_for_reference (vault:os.PathLike,
                           reference:Union[str,pathlib.Path])

Returns the index note of the specified reference in the vault.

Assumes that the reference folder has an index note named _index_{reference_name}.md and this note is the unique note in the vault with this filename.

Raises

• TypeError
  • If reference is not a str or PathLike.
• NoteDoesNotExistError
  • If a note of the name _index_{reference_name}.md does not exist in the vault.

	Type	Details
vault	PathLike	The vault in which the reference folder resides.
reference	typing.Union[str, pathlib.Path]	- The reference. Is either - a str, in which case the reference folder will be the folder containing the (unique) note of the name _index_{reference}.md, - or a Path object (not just a pathlike!) relative to vault, in which case the path will be the path to the reference folder.
Returns	VaultNote

The index_note_for_reference method obtains the index note of the specified reference in the vault.

vault = _test_directory() / 'test_vault_5'
index_note_1 = index_note_for_reference(vault, reference='number_theory_reference_1')
assert index_note_1.name == '_index_number_theory_reference_1'

index_note_2 = index_note_for_reference(vault, reference=Path('number_theory') / 'number_theory_reference_1')
assert index_note_2.name == '_index_number_theory_reference_1'

---

source

reference_directory

 reference_directory (vault:os.PathLike,
                      reference:Union[str,pathlib.Path])

Returns the path to the reference directory in a vault.

Assumes that the reference folder has an index note named _index_{reference_name}.md, this note is the unique note in the vault with this filename, and the cache in the VaultNote class for vault is updated.

Raises

• TypeError
  • If reference is not a str or PathLike.

	Type	Details
vault	PathLike	The vault in which the reference folder resides.
reference	typing.Union[str, pathlib.Path]	- The reference. Is either - a str, in which case the reference folder will be the folder containing the (unique) note of the name _index_{reference}.md, - or a Path object (not just a pathlike!) relative to vault, in which case the path will be the path to the reference folder.
Returns	Path	Relative to vault.

The reference_directory method obtains the root directory for the reference:

vault = _test_directory() / 'test_vault_5'
dir = reference_directory(vault, reference='number_theory_reference_1')

If the vault does not have an index note for the specified reference, then a NoteDoesNotExistError is raised:

with ExceptionExpected(NoteDoesNotExistError):
    thing = reference_directory(vault, reference='bad_number_theory_reference_without_an_index_note')
    print(thing)

Deleting a reference folder

---

source

delete_reference_folder

 delete_reference_folder (vault:os.PathLike,
                          reference:Union[str,os.PathLike],
                          verbose:bool=True, confirm:bool=True)

Deletes a reference folder along with the associated template note and the reference note, both of which are outside the reference folder.

Assumes that - the reference folder, if it exists, has an index note named _index_{reference_name}.md and this note is the unique note in the vault with this filename. - the template note, if it exists, is named _template_{reference_name}.md and is the unique note in the vault with this filename. - the reference note, if it exists, is named _reference_{reference_name}.md and is the unique note in the vault with this filename.

If the template/reference note for the reference is not unique, then the deletion does not proceed. On the other hand, even if a template/reference note does not exist, then the deletion proceeds.

Note that links to notes in the reference folder are preserved.

Raises

• FileNotFoundError
  • If the specified reference folder does not exist.
• NoteDoesNotExistError
  • If the index note for the reference folder does not exist in the vault.
• NoteNotUniqueError
  • If the index note, template note, or reference note for the reference folder is not unique in the vault.

	Type	Default	Details
vault	PathLike		The vault in which the reference folder resides.
reference	typing.Union[str, os.PathLike]		The reference to delete. Is either a str, in which case the folder to delete will be the folder containing the (unique) note of the name _index_{reference}.md, or a path relative to vault.
verbose	bool	True
confirm	bool	True	If True, prompts the user to confirm the deletion of the folder.
Returns	None

The delete_reference_folder method deletes the reference folder itself as well as the peripheral files for the reference (the template file and reference file) which are outside of the reference folder itself.

# TODO: make this example mock os.remove instead of copying the vault.
with (tempfile.TemporaryDirectory(prefix='temp_dir', dir=os.getcwd()) as temp_dir,
      mock.patch('__main__.input', return_value='Y') as mock_input):
    temp_vault = Path(temp_dir) / 'test_vault_5'
    shutil.copytree(_test_directory() / 'test_vault_5', temp_vault)
    
    delete_reference_folder(temp_vault, reference='number_theory_reference_1')
    assert 'number_theory_reference_1' not in os.listdir(temp_vault / 'number_theory')
    assert not VaultNote(temp_vault, name='_template_number_theory_reference_1').exists()
    assert not VaultNote(temp_vault, name='_reference_number_theory_reference_1').exists()

Identified reference 'number_theory_reference_1' in the vault 'c:\Users\hyunj\Documents\Development\Python\trouver\nbs\temp_dirkhkma_40\test_vault_5' as the folder 'c:\Users\hyunj\Documents\Development\Python\trouver\nbs\temp_dirkhkma_40\test_vault_5\number_theory\number_theory_reference_1'...
Deleting...
Deleted reference.

Helper methods for setting up new reference folders

Making a new reference folder takes some annoying amount of work.

test_vault = _test_directory() / 'test_vault_5'
template_vault_note = VaultNote(test_vault, name='_template_glossary')
assert template_vault_note.exists()
with (mock.patch('__main__.VaultNote') as mock_VaultNote,
      mock.patch('__main__.MarkdownFile.from_vault_note') as mock_markdownfile_from_vault_note):
    _make_glossary_file(
        Path('mock_path_1') / 'test_reference_1', 'test_reference_1', test_vault, '_glossary_notation_index')
    
    test_eq(mock_VaultNote.call_count, 2)
    mock_VaultNote.assert_called_with(test_vault, rel_path=Path('mock_path_1') / 'test_reference_1' / '_glossary_test_reference_1.md')
    mock_VaultNote.return_value.create.assert_called_once()
    mock_markdownfile_from_vault_note.return_value.write.assert_called_once()

test_vault = _test_directory() / 'test_vault_5'
with (mock.patch('__main__.VaultNote') as mock_VaultNote,
      mock.patch('__main__.os.mkdir') as mock_os_mkdir):
    _make_temp_folder(
        Path('mock_path_1') / 'test_reference_1', 'test_reference_1', test_vault)
    
    mock_os_mkdir.assert_called_once_with(test_vault / 'mock_path_1' / 'test_reference_1' / '_temp')
    mock_VaultNote.assert_called_once_with(test_vault, rel_path=Path('mock_path_1') / 'test_reference_1' / '_temp' / '_index_temp_test_reference_1.md')
    mock_VaultNote.return_value.create.assert_called_once()

Copy obsidian vault plugin configs

When an Obsidian vault has a lot of notes (on the order of 10000+ notes), Obsidian tends to experience significant lag. As such, it can be useful to open a reference folder as a “subvault”, i.e. a vault in itself, and in turn it is convenient to automatically copy settings from the “main” vault.

---

source

copy_obsidian_vault_configs

 copy_obsidian_vault_configs (vault:os.PathLike,
                              reference_directory:os.PathLike,
                              configs_folder:os.PathLike,
                              dirs_exist_ok:bool=False, ignore=None)

Copy the vault’s Obsidian config files into the reference directory.

configs_folder is copied into the destination vault / reference_directory / '.obsidian'.

shutil.copytree is used to copy the Obsidian configurations.

Raises - FileExistsError - If dirs_exist_ok is False and the destination vault / reference_directory / '.obsidian' already exists.

**See Also - copy_obsidian_vault_configs_with_nice_modifications

	Type	Default	Details
vault	PathLike
reference_directory	PathLike		The folder into which to copy the Obsidian configs. Relative to vault.
configs_folder	PathLike		The folder containing the Obsidian configs. This is either an absolute path or relative to the current working directory.
dirs_exist_ok	bool	False	If dirs_exist_ok is False and the destination folder already exists, then a FileExistsError is raised. If dirs_exist_ok is true, the copying operation will continue if it encounters existing directories, and files within the destination tree will be overwritten by corresponding files from the source tree. See also the shutil.copytree function.
ignore	NoneType	None	See documentation of the shutil.copytree function.
Returns	None

test_vault = _test_directory() / 'test_vault_5'
with (mock.patch('__main__.VaultNote') as mock_VaultNote,
      mock.patch('__main__.shutil.copytree') as mock_shutil_copytree):
    copy_obsidian_vault_configs(
        test_vault, Path('mock_path_1') / 'test_reference_1', test_vault / '.obsidian')
    
    mock_shutil_copytree.assert_called_once_with(
        test_vault / '.obsidian',
        test_vault / 'mock_path_1' / 'test_reference_1' / '.obsidian',
        dirs_exist_ok=False, ignore=None)

AssertionError: expected call not found.
Expected: copytree(WindowsPath('c:/Users/hyunj/Documents/Development/Python/trouver/nbs/_tests/test_vault_5/.obsidian'), WindowsPath('c:/Users/hyunj/Documents/Development/Python/trouver/nbs/_tests/test_vault_5/mock_path_1/test_reference_1/.obsidian'), dirs_exist_ok=False)
Actual: copytree(WindowsPath('c:/Users/hyunj/Documents/Development/Python/trouver/nbs/_tests/test_vault_5/.obsidian'), WindowsPath('c:/Users/hyunj/Documents/Development/Python/trouver/nbs/_tests/test_vault_5/mock_path_1/test_reference_1/.obsidian'), dirs_exist_ok=False, ignore=None)

If dirs_exist_okay = False but then the .obsidian folder of reference_directory already exists, then a FileExistsError is raised, cf. the description of the dirs_exist_ok parameter of the shutil.copytree function.

with (tempfile.TemporaryDirectory(prefix='temp_dir', dir=os.getcwd()) as temp_dir):
    # First copy over a testing vault
    temp_vault = Path(temp_dir) / 'test_vault_5'
    shutil.copytree(_test_directory() / 'test_vault_5', temp_vault)

    # Copy the obsidian vault configs once
    copy_obsidian_vault_configs(
        temp_vault,
        Path('number_theory') / 'number_theory_reference_1',
        temp_vault / '.obsidian',
        dirs_exist_ok = False)
    
    # Then, try copying the configs again in the same way
    # into the same destination.
    with ExceptionExpected(ex=FileExistsError):
        copy_obsidian_vault_configs(
            temp_vault,
            Path('number_theory') / 'number_theory_reference_1',
            temp_vault / '.obsidian',
            dirs_exist_ok = False)

If dirs_exist_okay = True, and if the destination vault / reference_directory / '.obsidian' already exists, then the copying operation will continue if it encounters existing directories, and existing files will be overwritten

with (tempfile.TemporaryDirectory(prefix='temp_dir', dir=os.getcwd()) as temp_dir):
    # First copy over a testing vault
    temp_vault = Path(temp_dir) / 'test_vault_5'
    shutil.copytree(_test_directory() / 'test_vault_5', temp_vault)

    # Copy the obsidian vault configs once
    reference_directory = Path('number_theory') / 'number_theory_reference_1'
    copy_obsidian_vault_configs(
        temp_vault,
        reference_directory,
        temp_vault / '.obsidian',
        dirs_exist_ok = True)

    # Try modifying one of the files in the newly copied configs folder:
    with open(temp_vault / reference_directory / '.obsidian' / 'templates.json', 'w') as file:
        file.write('')
    
    # os.startfile(temp_vault / reference_directory)
    # input()

    # Then, try copying the configs again in the same way
    # into the same destination.
    copy_obsidian_vault_configs(
        temp_vault,
        reference_directory,
        temp_vault / '.obsidian',
        dirs_exist_ok = True)
    # The configs folder is copied over once again.
    with open(temp_vault / reference_directory / '.obsidian' / 'templates.json', 'r') as file:
        test_ne(file.read(), '')

We can use the ignore parameter to ignore copying over certain files (say satisfying specified patterns). See the ignore parameter of the `shutil.copytree function.

with (tempfile.TemporaryDirectory(prefix='temp_dir', dir=os.getcwd()) as temp_dir):
    # First copy over a testing vault
    temp_vault = Path(temp_dir) / 'test_vault_5'
    shutil.copytree(_test_directory() / 'test_vault_5', temp_vault)

    # Copy the obsidian vault configs once
    reference_directory = Path('number_theory') / 'number_theory_reference_1'
    copy_obsidian_vault_configs(
        temp_vault,
        reference_directory,
        temp_vault / '.obsidian',
        dirs_exist_ok = True)

    # Try modifying two of the files in the newly copied configs folder:
    with open(temp_vault / reference_directory / '.obsidian' / 'templates.json', 'w') as file:
        file.write('')
    with open(temp_vault / reference_directory / '.obsidian' / 'app.json', 'w') as file:
        file.write('')
    
    # os.startfile(temp_vault / reference_directory)
    # input()

    # Then, try copying the configs again in the same way
    # into the same destination, except for files named 'templates.json'.
    copy_obsidian_vault_configs(
        temp_vault,
        reference_directory,
        temp_vault / '.obsidian',
        dirs_exist_ok = True,
        ignore = shutil.ignore_patterns('templates.json'))
    # The configs folder is copied over once again, except for the 'templates.json' file.
    with open(temp_vault / reference_directory / '.obsidian' / 'templates.json', 'r') as file:
        test_eq(file.read(), '')
    with open(temp_vault / reference_directory / '.obsidian' / 'app.json', 'r') as file:
        test_ne(file.read(), '')

The author of trouver makes two configuration modifications for each reference/subvault

1. In the author’s own fast-link-edit plugin, the author sets the referenceName field to whatever the name of the reference is in the vault
2. In the template core plugin, the author sets the folder field to ..

Moreover, sometimes one might want to make modifications to the configurations in one’s obsidian vaults; applying these modifications to all the configurations in the various subvaults would be tedious to do manually.

The below functions give ways to modify Obsidian plugin configurations and to copy and modify certain plugin configurations.

---

source

get_obsidian_vault_plugin_configs

 get_obsidian_vault_plugin_configs (vault:os.PathLike, plugin_name:str,
                                    plugin_is_core:bool)

Obtain the JSON object representing the data.json file of an Obsidian plugin.

This function assumes that the the Obsidian plugin exists in vault in that the plugin has a data.json file.

	Type	Details
vault	PathLike
plugin_name	str	The folder name of the Obsidian plugin. This can be found in the .obsidian directory in the vault.
plugin_is_core	bool	True if the plugin is a core Obsidian.md plugin. False if the plugin is a community plugin.
Returns	dict	A json dict.

test_vault = _test_directory() / 'test_vault_5' 
sample_output_1 = get_obsidian_vault_plugin_configs(test_vault, 'fast-link-edit', False)
test_eq(sample_output_1, {'referenceName': 'some_reference'})

sample_output_2 = get_obsidian_vault_plugin_configs(test_vault, 'templates', True)
test_eq(sample_output_2, {'folder': '_templates'})

---

source

modify_obsidian_vault_plugin_configs

 modify_obsidian_vault_plugin_configs (vault:os.PathLike, plugin_name:str,
                                       plugin_is_core:bool, field:str, val
                                       ue:Union[str,int,float,bool,NoneTyp
                                       e,list,dict])

Modify/set a top level field in an Obsidian vault plugin configs file.

Assumes that the Obsidian vault plugins configs are indented by 2 spaces.

Note that only top level values can be directly set by this function.

	Type	Details
vault	PathLike
plugin_name	str	The folder name of the Obsidian plugin. This can be found in the .obsidian directory in the vault.
plugin_is_core	bool	True if the plugin is a core Obsidian.md plugin. False if the plugin is a community plugin.
field	str	The field to modify
value	typing.Union[str, int, float, bool, NoneType, list, dict]	The JSON value to set the field as
Returns	None

with (tempfile.TemporaryDirectory(prefix='temp_dir', dir=os.getcwd()) as temp_dir):
    temp_vault = Path(temp_dir) / 'test_vault_5'
    shutil.copytree(_test_directory() / 'test_vault_5', temp_vault)

    modify_obsidian_vault_plugin_configs(temp_vault, 'fast-link-edit', False, 'referenceName', 'some_other_reference')
    sample_output_1 = get_obsidian_vault_plugin_configs(temp_vault, 'fast-link-edit', False)
    test_eq(sample_output_1, {'referenceName': 'some_other_reference'})

    modify_obsidian_vault_plugin_configs(temp_vault, 'templates', True, 'folder', '/')
    sample_output_2 = get_obsidian_vault_plugin_configs(temp_vault, 'templates', True)
    test_eq(sample_output_2, {'folder': '/'})

---

source

copy_obsidian_vault_configs_with_nice_modifications

 copy_obsidian_vault_configs_with_nice_modifications (vault:os.PathLike,
                                                      reference_directory:
                                                      os.PathLike, configs
                                                      _folder:os.PathLike,
                                                      reference_name:str=N
                                                      one, template_locati
                                                      on:str='/', dirs_exi
                                                      st_ok:bool=False,
                                                      ignore=None)

Copy the vault’s Obsidian config files into the reference directory and make some nice moodifications

As with copy_obsidian_vault_configs, configs_folder is copied into the destination vault / reference_directory / '.obsidian'.

Raises - FileExistsError - If dirs_exist_ok is False and the destination vault / reference_directory / '.obsidian' already exists.

	Type	Default	Details
vault	PathLike
reference_directory	PathLike		The folder into which to copy the Obsidian configs. Relative to vault.
configs_folder	PathLike		The folder containing the Obsidian configs to copy. This is either an absolute path or relative to the current working directory.
reference_name	str	None	The name of the reference and the value to change the referenceName field in the fast-link-edit plugin into. If None, then the reference name should be obtained as the name of reference_directory
template_location	str	/	The location of the template file(s) and the value to change the folder field in the templates plugin into.
dirs_exist_ok	bool	False	If dirs_exist_ok is False and the destination folder already exists, then a FileExistsError is raised. If dirs_exist_ok is true, the copying operation will continue if it encounters existing directories, and files within the destination tree will be overwritten by corresponding files from the source tree. See also the shutil.copytree function.
ignore	NoneType	None	See documentation of the shutil.copytree function.
Returns	None

# TODO: test
with (tempfile.TemporaryDirectory(prefix='temp_dir', dir=os.getcwd()) as temp_dir):
    temp_vault = Path(temp_dir) / 'test_vault_5'
    shutil.copytree(_test_directory() / 'test_vault_5', temp_vault)

    # Copy the configs in the folder `.obsidian` at the root of temp_vault into the `number_theory_reference_1` folder
    copy_obsidian_vault_configs_with_nice_modifications(
        temp_vault, Path('number_theory') / 'number_theory_reference_1', temp_vault / '.obsidian')

    configs_1 = get_obsidian_vault_plugin_configs(temp_vault / 'number_theory' / 'number_theory_reference_1', 'fast-link-edit', False)
    configs_2 = get_obsidian_vault_plugin_configs(temp_vault / 'number_theory' / 'number_theory_reference_1', 'templates', True)
    test_eq(configs_1['referenceName'], 'number_theory_reference_1')
    test_eq(configs_2['folder'], '/')

    # TODO: test `dirs_exist_ok` being tested.

Setting up a folder for a new reference

It takes a lot of time to setup a new reference in my Obsidian Math vault. I need to

1. Make index notes
2. Make notation notes
3. Make mathematician notes for authors
4. Make template notes
5. Make subfolders
6. Type in titles/subsections in index notes
7. Make reference notes

---

source

setup_folder_for_new_reference

 setup_folder_for_new_reference (reference_name:str, location:os.PathLike,
                                 authors:Union[str,list[str]],
                                 vault:os.PathLike, author_folder:os.PathL
                                 ike='_mathematicians', references_folder:
                                 os.PathLike='_references', templates_fold
                                 er:os.PathLike='_templates', template_fil
                                 e_name:str='_template_common', notation_i
                                 ndex_template_file_name:str='_template_no
                                 tation_index', glossary_template_file_nam
                                 e:str='_template_glossary', chapters:Opti
                                 onal[list[Union[str,list[str]]]]=None,
                                 setup_temp_folder:bool=True, make_second_
                                 template_file_in_reference_directory:bool
                                 =True, copy_obsidian_configs:Optional[os.
                                 PathLike]='.obsidian',
                                 overwrite:Optional[str]=None,
                                 confirm_overwrite:bool=True,
                                 verbose:bool=False)

Creates and sets up a new folder for a new reference.

More specifically, the following are set up:

1. The folder
2. An index file
3. Chapter folders and indices; the folder names are given by convert_title_to_folder_name(<title_with_numbering>) where title_with_numbering is the title of the chapter with its numbering if available, e.g. 1. Introduction.
4. Files in the Mathematicians folder, if applicable.
5. A reference file
   • For embedding in the standard information notes for the reference
6. A template file
7. A glossary file
8. A #_meta/reference tag for the new reference
9. A notation index file
10. Optionally, a _temp directory
11. Optionally, the ./obsidian config folder from the vault is copied.

After they are setup, the user should 1. Add content in the reference file. 2. Modify the last line of the template file.

Raises - FileExistsError - If overwrite is None and a folder of the name reference_name exists at Path(vault) / location.

	Type	Default	Details
reference_name	str		The name of the reference to be created; the folder’s name will be this string.
location	PathLike		The directory of the parent of the new folder to be made, relative to vault.
authors	typing.Union[str, list[str]]		Each str is the family name of each author.
vault	PathLike		The path to the Obsidian vault in which to make the reference folder.
author_folder	PathLike	_mathematicians	The directory where the author files are stored in. Relative to vault.
references_folder	PathLike	_references	The directory where the references files are stored in. Relative to vault.
templates_folder	PathLike	_templates	The directory where the template files are stored in. Relative to vault.
template_file_name	str	_template_common	The template file from which to base the template file of the new reference.
notation_index_template_file_name	str	_template_notation_index	The template file from which to base the notation index file of the new reference.
glossary_template_file_name	str	_template_glossary	The template file from which to base the glossary file of the new reference. Defaults to '_template_glossary'.
chapters	typing.Optional[list[typing.Union[str, list[str]]]]	None	A list where each item is either a str or a list of str. If the item is a str, then it should be the title of a chapter named in the format "1. {title}", "2. {title}", or "I. {title}", "II. {title}" etc. If the item is a list of str, then the 0th item should be the title of the chapter, formatted as in the previous sentence, and the other items should be titles of subchapters/subsections, also formatted in the same manner (e.g. if the subchapter is 7.2 of a book, then it should be "2. {title}"). Defaults to None, in which case no chapters are specified and hence no chapter folders and indices are created.
setup_temp_folder	bool	True	If True, creates a _temp folder with an index file. This folder serves to house notes auto-created from LaTeX text files before moving them to their correct directories. Defaults to True.
make_second_template_file_in_reference_directory	bool	True	If True, creates a copy of the template note within the directory for the reference.
copy_obsidian_configs	typing.Optional[os.PathLike]	.obsidian	The folder relative to vault from which to copy obsidian configs. If None, then no obsidian configs are copied to the reference folder. Defaults to .obsidian.
overwrite	typing.Optional[str]	None	Specifies if and how to overwrite the reference folder if it already exists. - If 'w', then deletes the contents of the existing reference folder, as well as the template and reference file before setting up the reference folder before creating the new reference folder. - If 'a', then overwrites the contents of the reference folder, but does not remove existing files/folders. - If None, then does not modify the existing reference folder and raises a FileExistsError.
confirm_overwrite	bool	True	Specifies whether or not to confirm the deletion of the reference folder if it already exists and if overwrite is 'w'. Defaults to True.
verbose	bool	False
Returns	None

We can set up a nicely formatted reference folder (without content) with the setup_folder_for_new_reference method. Try uncommenting the os.startfile and os.input lines to see what the vault looks like once the reference is setup.

with (tempfile.TemporaryDirectory(prefix='temp_dir', dir=os.getcwd()) as temp_dir):
    temp_vault = Path(temp_dir) / 'test_vault_5'
    shutil.copytree(_test_directory() / 'test_vault_5', temp_vault)

    chapters= [  # Chapters/sections and sections/subsections of the reference can be set up
        '0. Having a chapter 0 is fine',
        ['1. Introduction', '1.1. A subsection'],
        ['2. Basic ring theory', '2.1. Rings', '2.2. Integral domains', '2.3. Fields', '2.4 Fermat\'s Little Theorem'],
        '3. Chapter without subsection',
        ['A. Appendix: Set theory', 'A.1 Set Axioms', 'A.2 Constructions']
    ]
    setup_folder_for_new_reference(
        reference_name='kim_intro_num_theory', location='number_theory',
        authors='Kim', vault=temp_vault, chapters=chapters
        )

    # os.startfile(temp_vault)
    # input()
    # TODO: test that files that need to be created have been created.

# TODO: test overwrite and confirm_overwrite parameters
# TODO: give an example of verbose

Getting the chapters/sections from a file

Getting subfolders and index files of a reference

---

source

get_index_notes_from_subdirectory

 get_index_notes_from_subdirectory (vault:os.PathLike,
                                    subdirectory:os.PathLike,
                                    main_index_note:bool=False,
                                    as_vault_notes:bool=True)

Returns list of index note files for reference

	Type	Default	Details
vault	PathLike		The path to the Obsidian vault directory.
subdirectory	PathLike		The path, relative to vault of the subdirectory of of the vault for the reference.
main_index_note	bool	False	If True, include the main index note for the reference. This index note should be in the directory specified by subdirectory.
as_vault_notes	bool	True	If True, returns the [VaultNote](https://hyunjongkimmath.github.io/trouver/markdown.obsidian.vault.html#vaultnote) objects for the index notes. Otherwise, returns the paths to the index notes as paths, represented by str.
Returns	list		Either of the names of the index notes in the vault or of the index notes as VaultNote objects, depending on as_vault_notes.

# TODO: test

---

source

get_index_notes_from_index_note

 get_index_notes_from_index_note (vault:os.PathLike, reference_name:str,
                                  as_vault_notes:bool=True)

Returns the list of index notes for the reference in the order that they are listed in the reference’s main index note.

Does so by searching the “main” index note in the reference folder. Returns the index notes in order that they are listed in the main index note.

Assumes that the reference folder is “formatted correctly”. This includes the assumption that the main index note for the reference is the unique note named '_index_{reference_name}' in the vault.

Parameters

• vault - PathLike
  • The path to the Obsidian vault directory
• reference_name - str
  • The name of the reference folder in the vault.
• as_vault_notes - bool
  • If True, returns the [VaultNote](https://hyunjongkimmath.github.io/trouver/markdown.obsidian.vault.html#vaultnote) objects for the index notes. Otherwise, returns the paths to the index notes as paths, represented by str. Defaults to True.

Returns - list[Union[str, VaultNote]] - Either of the names of the index notes in the vault or of the index notes as VaultNote objects, depending on as_vault_notes.

See Also - [get_notes_from_index_note](https://hyunjongkimmath.github.io/trouver/markdown.obsidian.personal.index_notes.html#get_notes_from_index_note) in markdown.obsidian.personal.index_notes.

# TODO: test

Finding all reference folders in a vault

---

source

reference_folders_in_vault

 reference_folders_in_vault (vault:os.PathLike)

Returns a dict of reference folders in vault.

Parameters - vault - PathLike - The path to the Obsidian vault directory.

Returns - dict - The keys are str, each of which is the name of a reference. The values are path strings to the reference folder, relative to vault.

# TODO: example

Getting files in a reference folder

---

source

files_in_reference_folder

 files_in_reference_folder (vault:os.PathLike, reference:str,
                            as_list:bool=False,
                            search_index_notes:bool=False, exclude_notes_o
                            f_type:list[trouver.markdown.obsidian.personal
                            .note_type.PersonalNoteTypeEnum]=None)

Returns a dict or list of files in a reference folder of a vault.

TODO: also implement a method to get the files as listed in index notes.

Parameters - vault - PathLike - reference - str - Name of the reference folder in the vault. The folder must have the index note file '_index_{reference}.md', and there must not be two index note files of the same name in the vault. - as_list - bool - If True, then returns a list. Returns a dict otherwise. Defaults to False. - search_index_notes - bool - If True, then gets the notes by looking at the reference’s index notes and returns the notes as ordered by the index notes. - exclude_notes_of_type - list of markdown.obsidian.personal.note_type.PersonalNoteTypeEnum. - The notes of the types specified here will be excluded in the dict or list returned. Defaults to None, in which case

Returns - list[str] or dict[str, str] - Either a list of path strings or a dict whose keys are str and values are path strings. The keys are the names of the files. The Paths are relative to vault.

# TODO: examples