buku module
- class buku.BookmarkVar(id: int, url: str, title: str | None = None, tags_raw: str = '', desc: str = '', flags: int = 0)[source]
Bases:
NamedTuple
Bookmark data named tuple
- desc: str
Alias for field number 4
- flags: int
Alias for field number 5
- id: int
Alias for field number 0
- property immutable: bool
- property taglist: List[str]
- property tags: str
- tags_raw: str
Alias for field number 3
- title: str | None
Alias for field number 2
- url: str
Alias for field number 1
- class buku.BukuCrypt[source]
Bases:
object
Class to handle encryption and decryption of the database file. Functionally a separate entity.
Involves late imports in the static functions but it saves ~100ms each time. Given that encrypt/decrypt are not done automatically and any one should be called at a time, this doesn’t seem to be an outrageous approach.
- BLOCKSIZE = 65536
- CHUNKSIZE = 524288
- SALT_SIZE = 32
- static decrypt_file(iterations, dbfile=None)[source]
Decrypt the bookmarks database file.
- Parameters:
iterations (int) – Number of iterations for key generation.
dbfile (str, optional) – Custom database file path (including filename). The ‘.enc’ suffix must be omitted.
- class buku.BukuDb(json: str | None = None, field_filter: int = 0, chatty: bool = False, dbfile: str | None = None, colorize: bool = True)[source]
Bases:
object
Abstracts all database operations.
- conn
- Type:
sqlite database connection.
- cur
- Type:
sqlite database cursor.
- json
Empty string if results should be printed in JSON format to stdout. Nonempty string if results should be printed in JSON format to file. The string has to be a valid path. None if the results should be printed as human-readable plaintext.
- Type:
string
- field_filter
Indicates format for displaying bookmarks. Default is 0.
- Type:
int
- chatty
Sets the verbosity of the APIs. Default is False.
- Type:
bool
- add_rec(url: str, title_in: str | None = None, tags_in: str | None = None, desc: str | None = None, immutable: bool = False, delay_commit: bool = False, fetch: bool = True, url_redirect: bool = False, tag_redirect: bool | str = False, tag_error: bool | str = False, del_error: Set[int] | range | None = None) int [source]
Add a new bookmark.
- Parameters:
url (str) – URL to bookmark.
title_in (str, optional) – Title to add manually. Default is None.
tags_in (str, optional) – Comma-separated tags to add manually. Must start and end with comma. Default is None.
desc (str, optional) – Description of the bookmark. Default is None.
immutable (bool) – Indicates whether to disable title fetch from web. Default is False.
delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.
fetch (bool) – Fetch page from web and parse for data. Required fetch-status params to take effect.
url_redirect (bool) – Bookmark the URL produced after following all PERMANENT redirects.
tag_redirect (bool | str) – Adds a tag by the given pattern if the url resolved to a PERMANENT redirect. (True means the default pattern ‘http:{}’.)
tag_error (bool | str) – Adds a tag by the given pattern if the url resolved to a HTTP error. (True means the default pattern ‘http:{}’.)
del_error (int{} | range, optional) – Do not add the bookmark if HTTP response status is in the given set or range. Also prevents the bookmark from being added on a network error.
- Returns:
DB index of new bookmark on success, None on failure.
- Return type:
int
- append_tag_at_index(index, tags_in, delay_commit=False)[source]
Append tags to bookmark tagset at index.
- Parameters:
index (int | int[] | int{} | range, optional) – DB index of the record. 0 or empty indicates all records.
tags_in (str) – Comma-separated tags to add manually.
delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.
- Returns:
True on success, False on failure.
- Return type:
bool
- auto_import_from_browser(firefox_profile=None)[source]
Import bookmarks from a browser default database file.
Supports Firefox, Google Chrome, Vivaldi, and Microsoft Edge.
- Returns:
True on success, False on failure.
- Return type:
bool
- browse_by_index(index=0, low=0, high=0, is_range=False)[source]
Open URL at index or range of indices in browser.
- Parameters:
index (int) – Index to browse. 0 opens a random bookmark.
low (int) – Actual lower index of range.
high (int) – Higher index of range.
is_range (bool) – A range is passed using low and high arguments. If True, index is ignored. Default is False.
- Returns:
True on success, False on failure.
- Return type:
bool
- browse_cached_url(arg)[source]
Open URL at index or URL.
- Parameters:
arg (str) – Index or url to browse
- Returns:
Wayback Machine URL, None if not cached
- Return type:
str
- cleardb()[source]
Drops the bookmark table if it exists.
- Returns:
True on success, False on failure.
- Return type:
bool
- close_quit(exitval=0)[source]
Close a DB connection and exit.
- Parameters:
exitval (int) – Program exit value.
- compactdb(index: int, delay_commit: bool = False)[source]
When an entry at index is deleted, move the last entry in DB to index, if index is lesser.
- Parameters:
index (int) – DB index of deleted entry.
delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.
- delete_rec(index: int | None = None, low: int = 0, high: int = 0, is_range: bool = False, delay_commit: bool = False, chatty: bool | None = None) bool [source]
Delete a single record or remove the table if index is 0.
- Parameters:
index (int, optional) – DB index of deleted entry.
low (int) – Actual lower index of range.
high (int) – Actual higher index of range.
is_range (bool) – A range is passed using low and high arguments. An index is ignored if is_range is True.
delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.
chatty (Optional[bool]) – Override for self.chatty
- Raises:
TypeError – If any of index, low, or high variable is not integer.
- Returns:
True on success, False on failure.
- Return type:
bool
Examples
>>> from tempfile import NamedTemporaryFile >>> import buku >>> sdb = buku.BukuDb(dbfile=NamedTemporaryFile().name) # single record database >>> sdb.add_rec('https://example.com') 1 >>> sdb.delete_rec(1) Index 1 deleted True
Delete record with default range.
>>> sdb = buku.BukuDb(dbfile=NamedTemporaryFile().name) >>> sdb.add_rec('https://example.com') 1 >>> sdb.delete_rec(is_range=True) Remove ALL bookmarks? (y/n): y All bookmarks deleted True
Running the function without any parameter will raise TypeError.
>>> sdb = buku.BukuDb(dbfile=NamedTemporaryFile().name) >>> sdb.add_rec('https://example.com') 1 >>> sdb.delete_rec() Traceback (most recent call last): ... TypeError: index, low, or high variable is not integer
Negative number on high and low parameters when is_range is True will log error and return False
>>> edb = buku.BukuDb(dbfile=NamedTemporaryFile().name) >>> edb.delete_rec(low=-1, high=-1, is_range=True) False
Remove the table
>>> sdb = buku.BukuDb(dbfile=NamedTemporaryFile().name) >>> sdb.delete_rec(0) Remove ALL bookmarks? (y/n): y All bookmarks deleted True
- delete_rec_all(delay_commit=False)[source]
Removes all records in the Bookmarks table.
- Parameters:
delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.
- Returns:
True on success, False on failure.
- Return type:
bool
- delete_resultset(results)[source]
Delete search results in descending order of DB index.
Indices are expected to be unique and in ascending order.
Notes
This API forces a delayed commit.
- Parameters:
results (list of tuples) – List of results to delete from DB.
- Returns:
True on success, False on failure.
- Return type:
bool
- delete_tag_at_index(index, tags_in, delay_commit=False, chatty=True)[source]
Delete tags from bookmark tagset at index.
- Parameters:
index (int | int[] | int{} | range, optional) – DB index of bookmark record. 0 or empty indicates all records.
tags_in (str) – Comma-separated tags to delete manually.
delay_commit (bool) – True if record should not be committed to the DB, leaving commit responsibility to caller. Default is False.
chatty (bool) – Skip confirmation when set to False.
- Returns:
True on success, False on failure.
- Return type:
bool
- edit_update_rec(index, immutable=None)[source]
Edit in editor and update a record.
- Parameters:
index (int) – DB index of the record. Last record, if index is -1.
immutable (bool, optional) – Disable title fetch from web if True. Default is None (no change).
- Returns:
True if updated, else False.
- Return type:
bool
- exclude_results_from_search(search_results, without, deep)[source]
Excludes records that match keyword search using without parameters
- Parameters:
search_results (list) – List of search results
without (list of str) – Keywords to search.
deep (bool) – True to search for matching substrings.
- Returns:
List of search results.
- Return type:
list
- exportdb(filepath: str, resultset: List[BookmarkVar] | None = None) bool [source]
Export DB bookmarks to file. Exports full DB, if resultset is None. Additionally, if run after a (batch) update with export_on, only export those records.
If destination file name ends with ‘.db’, bookmarks are exported to a buku database file. If destination file name ends with ‘.md’, bookmarks are exported to a Markdown file. If destination file name ends with ‘.org’ bookmarks are exported to an org file. If destination file name ends with ‘.xbel’ bookmarks are exported to a XBEL file. Otherwise, bookmarks are exported to a Firefox bookmarks.html formatted file.
- Parameters:
filepath (str) – Path to export destination file.
resultset (list of tuples) – List of results to export. Use None to get current DB. Ignored if run after a (batch) update with export_on.
- Returns:
True on success, False on failure.
- Return type:
bool
- fixtags()[source]
Undocumented API to fix tags set in earlier versions.
Functionalities:
Remove duplicate tags
Sort tags
Use lower case to store tags
- static get_default_dbdir()[source]
Determine the directory path where dbfile will be stored.
If the platform is Windows, use %APPDATA% else if $XDG_DATA_HOME is defined, use it else if $HOME exists, use it else use the current directory.
- Returns:
Path to database file.
- Return type:
str
- get_max_id() int [source]
Fetch the ID of the last record.
- Returns:
ID of the record if any record exists, else None.
- Return type:
int
- get_rec_all()[source]
Get all the bookmarks in the database.
- Returns:
A list of tuples representing bookmark records.
- Return type:
list
- get_rec_all_by_ids(indices: Sequence[int] | Set[int] | range)[source]
Get all the bookmarks in the database.
- Parameters:
indices (int[] | int{} | range) – DB indices of bookmark records.
- Returns:
A list of tuples representing bookmark records.
- Return type:
list
- get_rec_by_id(index: int) BookmarkVar | None [source]
Get a bookmark from database by its ID.
- Parameters:
index (int) – DB index of bookmark record.
- Returns:
Bookmark data, or None if index is not found.
- Return type:
BookmarkVar or None
- get_rec_id(url)[source]
Check if URL already exists in DB.
- Parameters:
url (str) – A URL to search for in the DB.
- Returns:
DB index, or None if URL not found in DB.
- Return type:
int
- get_rec_ids(urls: Sequence[str] | Set[str])[source]
Check if URL already exists in DB.
- Parameters:
urls (str[] | str{}) – URLs to search for in the DB.
- Returns:
A list of DB indices.
- Return type:
list
- get_tag_all()[source]
Get list of tags in DB.
- Returns:
- (list of unique tags sorted alphabetically,
dictionary of {tag: usage_count}).
- Return type:
tuple
- get_tagstr_from_taglist(id_list, taglist)[source]
Get a string of delimiter-separated (and enclosed) string of tags from a dictionary of tags by matching ids.
The inputs are the outputs from BukuDb.get_tag_all().
- Parameters:
id_list (list) – List of ids.
taglist (list) – List of tags.
- Returns:
Delimiter separated and enclosed list of tags.
- Return type:
str
- importdb(filepath, tacit=False)[source]
Import bookmarks from an HTML or a Markdown file.
Supports Firefox, Google Chrome, and IE exported HTML bookmarks. Supports XBEL standard bookmarks. Supports Markdown files with extension ‘.md, .org’. Supports importing bookmarks from another buku database file.
- Parameters:
filepath (str) – Path to file to import.
tacit (bool) – If True, no questions asked and folder names are automatically imported as tags from bookmarks HTML. If True, automatic timestamp tag is NOT added. Default is False.
- Returns:
True on success, False on failure.
- Return type:
bool
- static initdb(dbfile: str | None = None, chatty: bool = False) Tuple[Connection, Cursor] [source]
Initialize the database connection.
Create DB file and/or bookmarks table if they don’t exist. Alert on encryption options on first execution.
- Parameters:
dbfile (str, optional) – Custom database file path (including filename).
chatty (bool) – If True, shows informative message on DB creation.
- Returns:
(connection, cursor).
- Return type:
tuple
- list_using_id(ids=[])[source]
List entries in the DB using the specified id list.
- Parameters:
ids (list of ids in string form) –
- Return type:
list
- load_chrome_database(path, unique_tag, add_parent_folder_as_tag)[source]
Open Chrome Bookmarks JSON file and import data.
- Parameters:
path (str) – Path to Google Chrome bookmarks file.
unique_tag (str) – Timestamp tag in YYYYMonDD format.
add_parent_folder_as_tag (bool) – True if bookmark parent folders should be added as tags else False.
- load_edge_database(path, unique_tag, add_parent_folder_as_tag)[source]
Open Edge Bookmarks JSON file and import data.
- Parameters:
path (str) – Path to Microsoft Edge bookmarks file.
unique_tag (str) – Timestamp tag in YYYYMonDD format.
add_parent_folder_as_tag (bool) – True if bookmark parent folders should be added as tags else False.
- load_firefox_database(path, unique_tag, add_parent_folder_as_tag)[source]
Connect to Firefox sqlite db and import bookmarks into BukuDb.
- Parameters:
path (str) – Path to Firefox bookmarks sqlite database.
unique_tag (str) – Timestamp tag in YYYYMonDD format.
add_parent_folder_as_tag (bool) – True if bookmark parent folders should be added as tags else False.
- mergedb(path)[source]
Merge bookmarks from another buku database file.
- Parameters:
path (str) – Path to DB file to merge.
- Returns:
True on success, False on failure.
- Return type:
bool
- print_rec(index: int | Sequence[int] | Set[int] | range | None = 0, low: int = 0, high: int = 0, is_range: bool = False) bool [source]
Print bookmark details at index or all bookmarks if index is 0.
A negative index behaves like tail, if title is blank show “Untitled”.
Empty database check will run when index < 0 and is_range is False.
- Parameters:
index (int | int[] | int{} | range, optional) – DB index(es) of record(s) to print. 0 or empty prints all records. Negative value prints out last index rows.
low (int) – Actual lower index of range.
high (int) – Actual higher index of range.
is_range (bool) – A range is passed using low and high arguments. An index is ignored if is_range is True.
- Returns:
True on success, False on failure.
- Return type:
bool
Examples
>>> import buku >>> from tempfile import NamedTemporaryFile >>> edb = buku.BukuDb(dbfile=NamedTemporaryFile().name) # empty database >>> edb.print_rec() True
Print negative index on empty database will log error and return False
>>> edb.print_rec(-3) False
print non empty database with default argument.
>>> sdb = buku.BukuDb(dbfile=NamedTemporaryFile().name) # single record database >>> sdb.add_rec('https://example.com') 1 >>> assert sdb.print_rec() 1. Example Domain > https://example.com
Negative number on high and low parameters when is_range is True will log error and return False
>>> sdb.print_rec(low=-1, high=-1, is_range=True) False >>> edb.print_rec(low=-1, high=-1, is_range=True) False
- refreshdb(index: int | Sequence[int] | Set[int] | range | None, threads: int, url_redirect: bool = False, tag_redirect: bool | str = False, tag_error: bool | str = False, del_error: Set[int] | range | None = None, export_on: Set[int] | range | None = None, update_title: bool = True, custom_url: str | None = None, custom_tags: str | None = None, delay_delete: bool = False) bool [source]
Refresh ALL (or specified) records in the database.
Fetch title for each bookmark from the web and update the records. Doesn’t update the title if fetched title is empty.
Notes
This API doesn’t change DB index, URL or tags of a bookmark. (Unless one or more fetch-status parameters are supplied.) This API is verbose.
- Parameters:
index (int | int[] | int{} | range, optional) – DB index(es) of record(s) to update. 0 or empty value indicates all records.
threads (int) – Number of threads to use to refresh full DB. Default is 4.
url_redirect (bool) – Update the URL to one produced after following all PERMANENT redirects. (This could fail if the new URL is bookmarked already.)
tag_redirect (bool | str) – Adds a tag by the given pattern if the url resolved to a PERMANENT redirect. (True means the default pattern ‘http:{}’.)
tag_error (bool | str) – Adds a tag by the given pattern if the url resolved to a HTTP error. (True means the default pattern ‘http:{}’.)
del_error (int{} | range, optional) – Delete the bookmark if HTTP response status is in the given set or range.
export_on (int{} | range, optional) – Limit the export to URLs returning one of given HTTP codes; store old URLs.
update_title (bool) – Update titles/descriptions. (Can be turned off for network testing.)
custom_url (str, optional) – Override URL to fetch. (Use for network testing of a single record before updating it.)
custom_tags (str, optional) – Overwrite all tags. (Use to combine network testing with tags overwriting.)
delay_delete (bool) – Delay scheduled deletions by del_error. (Use for network testing during update.)
- Returns:
True on success, False on failure. (Deletion by del_error counts as success.)
- Return type:
bool
- replace_tag(orig: str, new: List[str] = [])[source]
Replace original tag by new tags in all records.
Remove original tag if new tag is empty.
- Parameters:
orig (str) – Original tag.
new (list) – Replacement tags.
- Raises:
ValueError – Invalid input(s) provided.:
RuntimeError – Tag deletion failed.:
- search_by_tag(tags: str | None) List[BookmarkVar] [source]
Search bookmarks for entries with given tags.
- Parameters:
tags (str) – String of tags to search for. Retrieves entries matching ANY tag if tags are delimited with ‘,’. Retrieves entries matching ALL tags if tags are delimited with ‘+’.
- Returns:
List of search results.
- Return type:
list
- search_keywords_and_filter_by_tags(keywords: List[str], all_keywords: bool, deep: bool, regex: bool, stag: str) List[BookmarkVar] [source]
Search bookmarks for entries with keywords and specified criteria while filtering out entries with matching tags.
- Parameters:
keywords (list of str) – Keywords to search.
all_keywords (bool) – True to return records matching ALL keywords. False to return records matching ANY keyword.
deep (bool) – True to search for matching substrings.
regex (bool) – Match a regular expression if True.
stag (str) – String of tags to search for. Retrieves entries matching ANY tag if tags are delimited with ‘,’. Retrieves entries matching ALL tags if tags are delimited with ‘+’.
- Returns:
List of search results.
- Return type:
list
- searchdb(keywords: List[str], all_keywords: bool = False, deep: bool = False, regex: bool = False) List[BookmarkVar] [source]
Search DB for entries where tags, URL, or title fields match keywords.
- Parameters:
keywords (list of str) – Keywords to search.
all_keywords (bool) – True to return records matching ALL keywords. False (default value) to return records matching ANY keyword.
deep (bool) – True to search for matching substrings. Default is False.
regex (bool) – Match a regular expression if True. Default is False.
- Returns:
List of search results.
- Return type:
list
- set_tag(cmdstr, taglist)[source]
Append, overwrite, remove tags using the symbols >>, > and << respectively.
- Parameters:
cmdstr (str) – Command pattern.
taglist (list) – List of tags.
- Returns:
Number of indices updated on success, -1 on failure, -2 on no symbol found.
- Return type:
int
- suggest_similar_tag(tagstr)[source]
Show list of tags those go together in DB.
- Parameters:
tagstr (str) – Original tag string.
- Returns:
DELIM separated string of tags.
- Return type:
str
- tnyfy_url(index: int | None = None, url: str | None = None, shorten: bool = True) str | None [source]
Shorten a URL using Google URL shortener.
- Parameters:
index (int, optional (if URL is provided)) – DB index of the bookmark with the URL to shorten. Default is None.
url (str, optional (if index is provided)) – URL to shorten.
shorten (bool) – True to shorten, False to expand. Default is False.
- Returns:
Shortened url on success, None on failure.
- Return type:
str
- traverse_bm_folder(sublist, unique_tag, folder_name, add_parent_folder_as_tag)[source]
Traverse bookmark folders recursively and find bookmarks.
- Parameters:
sublist (list) – List of child entries in bookmark folder.
unique_tag (str) – Timestamp tag in YYYYMonDD format.
folder_name (str) – Name of the parent folder.
add_parent_folder_as_tag (bool) – True if bookmark parent folders should be added as tags else False.
- Returns:
Bookmark record data.
- Return type:
tuple
- update_rec(index: int | Sequence[int] | Set[int] | range | None, url: str | None = None, title_in: str | None = None, tags_in: str | None = None, desc: str | None = None, immutable: bool | None = None, threads: int = 4, url_redirect: bool = False, tag_redirect: bool | str = False, tag_error: bool | str = False, del_error: Set[int] | range | None = None, export_on: Set[int] | range | None = None) bool [source]
Update an existing record at (each) index.
Update all records if index is 0 or empty, and url is not specified. URL is an exception because URLs are unique in DB.
- Parameters:
index (int | int[] | int{} | range, optional) – DB index(es) of record(s). 0 or empty value indicates all records.
url (str, optional) – Bookmark address.
title_in (str, optional) – Title to add manually.
tags_in (str, optional) – Comma-separated tags to add manually. Must start and end with comma. Prefix with ‘+,’ to append to current tags. Prefix with ‘-,’ to delete from current tags.
desc (str, optional) – Description of bookmark.
immutable (bool, optional) – Disable title fetch from web if True. Default is None (no change).
threads (int) – Number of threads to use to refresh full DB. Default is 4.
url_redirect (bool) – Update the URL to one produced after following all PERMANENT redirects. (This could fail if the new URL is bookmarked already.)
tag_redirect (bool | str) – Adds a tag by the given pattern if the url resolved to a PERMANENT redirect. (True means the default pattern ‘http:{}’.)
tag_error (bool | str) – Adds a tag by the given pattern if the url resolved to a HTTP error. (True means the default pattern ‘http:{}’.)
del_error (int{} | range, optional) – Delete the bookmark if HTTP response status is in the given set or range. Does NOT cause deletion of the bookmark on a network error.
export_on (int{} | range, optional) – Limit the export to URLs returning one of given HTTP codes; store old URLs.
- Returns:
True on success, False on failure. (Deletion by del_error counts as success.)
- Return type:
bool
- class buku.ExtendedArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)[source]
Bases:
ArgumentParser
Extend classic argument parser.
- static is_colorstr(arg)[source]
Check if a string is a valid color string.
- Parameters:
arg (str) – Color string to validate.
- Returns:
Same color string that was passed as an argument.
- Return type:
str
- Raises:
ArgumentTypeError – If the arg is not a valid color string.
- print_help(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)[source]
Print help prompt.
- Parameters:
file (file) – File to write program info to. Default is sys.stdout.
- class buku.FetchResult(url, title, desc, keywords, mime, bad, fetch_status)[source]
Bases:
NamedTuple
- bad: bool
Alias for field number 5
- desc: str
Alias for field number 2
- fetch_status: int | None
Alias for field number 6
- keywords: str
Alias for field number 3
- mime: bool
Alias for field number 4
- tags(*, keywords: bool = True, redirect: bool | str = False, error: bool | str = False) str [source]
- title: str
Alias for field number 1
- url: str
Alias for field number 0
- buku.bookmark_vars(xs)
- buku.browse(url)[source]
Duplicate stdin, stdout and open URL in default browser.
Note
Duplicates stdin and stdout in order to suppress showing errors on the terminal.
- Parameters:
url (str) – URL to open in browser.
- buku.suppress_browser_output
True if a text based browser is detected. Must be initialized (as applicable) to use the API.
- Type:
bool
- buku.override_text_browser
If True, tries to open links in a GUI based browser.
- Type:
bool
- buku.check_stdout_encoding()[source]
Make sure stdout encoding is utf-8.
If not, print error message and instructions, then exit with status 1.
This function is a no-op on win32 because encoding on win32 is messy, and let’s just hope for the best. /s
- buku.convert_bookmark_set(bookmark_set: List[BookmarkVar], export_type: str, old: Dict[str, str | BookmarkVar] | None = None) ConverterResult [source]
Convert list of bookmark set into multiple data format.
- Parameters:
bookmark_set (bookmark set) –
export_type (one of supported type: markdown, html, org, XBEL) –
old (cached values of deleted records/replaced URLs to save) –
- Return type:
converted data and count of converted bookmark set
- buku.convert_tags_to_org_mode_tags(tags: str) str [source]
convert buku tags to org-mode compatible tags.
- buku.copy_to_clipboard(content)[source]
Copy content to clipboard
- Parameters:
content (str) – Content to be copied to clipboard
- buku.delim_wrap(token)[source]
Returns token string wrapped in delimiters.
- Parameters:
token (str) – String item to wrap with DELIM.
- Returns:
Token string wrapped by DELIM.
- Return type:
str
- buku.edit_at_prompt(obj, nav, suggest=False)[source]
Edit and add or update a bookmark.
- Parameters:
obj (BukuDb instance) – A valid instance of BukuDb class.
nav (str) – Navigation command argument passed at prompt by user.
suggest (bool) – If True, suggest similar tags on new bookmark addition.
- buku.edit_rec(editor, url, title_in, tags_in, desc)[source]
Edit a bookmark record.
- Parameters:
editor (str) – Editor to open.
URL (str) – URL to open.
title_in (str) – Title to add manually.
tags_in (str) – Comma-separated tags to add manually.
desc (str) – Bookmark description.
- Returns:
Parsed results from parse_temp_file_content().
- Return type:
tuple
- buku.fetch_data(url: str, http_head: bool = False) FetchResult [source]
Handle server connection and redirections.
- Parameters:
url (str) – URL to fetch.
http_head (bool) – If True, send only HTTP HEAD request. Default is False.
- Returns:
(url, title, desc, keywords, mime, bad, fetch_status)
- Return type:
- buku.format_json(resultset, single_record=False, field_filter=0)[source]
Return results in JSON format.
- Parameters:
resultset (list) – Search results from DB query.
single_record (bool) – If True, indicates only one record. Default is False.
field_filter (int) – Indicates format for displaying bookmarks. Default is 0 (“all fields”).
- Returns:
Record(s) in JSON format.
- Return type:
json
- buku.gen_auto_tag()[source]
Generate a tag in Year-Month-Date format.
- Returns:
New tag as YYYYMonDD.
- Return type:
str
- buku.get_PoolManager()[source]
Creates a pool manager with proxy support, if applicable.
- Returns:
ProxyManager if https_proxy is defined, PoolManager otherwise.
- Return type:
ProxyManager or PoolManager
- buku.get_data_from_page(resp)[source]
Detect HTTP response encoding and invoke parser with decoded data.
- Parameters:
resp (HTTP response) – Response from GET request.
- Returns:
(title, description, keywords).
- Return type:
tuple
- buku.get_firefox_profile_names(path)[source]
List folder and detect default Firefox profile names for all installs.
- Returns:
profiles – All default Firefox profile names.
- Return type:
[str]
- buku.import_firefox_json(json, add_bookmark_folder_as_tag=False, unique_tag=None)[source]
Open Firefox JSON export file and import data. Ignore ‘SmartBookmark’ and ‘Separator’ entries.
Needed/used fields out of the JSON schema of the bookmarks:
title : the name/title of the entry tags : ‘,’ separated tags for the bookmark entry typeCode : 1 - uri, 2 - subfolder, 3 - separator annos/{name,value} : following annotation entries are used
name : Places/SmartBookmark : identifies smart folder, ignored name : bookmarkPropereties/description : detailed bookmark entry description
children : for subfolders, recurse into the child entries
- Parameters:
path (str) – Path to Firefox JSON bookmarks file.
unique_tag (str) – Timestamp tag in YYYYMonDD format.
add_bookmark_folder_as_tag (bool) – True if bookmark parent folder should be added as tags else False.
- buku.import_html(html_soup: BeautifulSoup, add_parent_folder_as_tag: bool, newtag: str, use_nested_folder_structure: bool = False)[source]
Parse bookmark HTML.
- Parameters:
html_soup (BeautifulSoup object) – BeautifulSoup representation of bookmark HTML.
add_parent_folder_as_tag (bool) – True if bookmark parent folders should be added as tags else False.
newtag (str) – A new unique tag to add to imported bookmarks.
use_nested_folder_structure (bool) – True if all bookmark parent folder should be added, not just direct parent else False add_parent_folder_as_tag must be True for this flag to have an effect
- Returns:
Parsed result.
- Return type:
tuple
- buku.import_md(filepath: str, newtag: str | None)[source]
Parse bookmark Markdown file.
- Parameters:
filepath (str) – Path to Markdown file.
newtag (str, optional) – New tag for bookmarks in Markdown file.
- Returns:
Parsed result.
- Return type:
tuple
- buku.import_org(filepath: str, newtag: str | None)[source]
Parse bookmark org file.
- Parameters:
filepath (str) – Path to org file.
newtag (str, optional) – New tag for bookmarks in org file.
- Returns:
Parsed result.
- Return type:
tuple
- buku.import_xbel(html_soup: BeautifulSoup, add_parent_folder_as_tag: bool, newtag: str, use_nested_folder_structure: bool = False)[source]
Parse bookmark XBEL.
- Parameters:
html_soup (BeautifulSoup object) – BeautifulSoup representation of bookmark HTML.
add_parent_folder_as_tag (bool) – True if bookmark parent folders should be added as tags else False.
newtag (str) – A new unique tag to add to imported bookmarks.
use_nested_folder_structure (bool) – True if all bookmark parent folder should be added, not just direct parent else False add_parent_folder_as_tag must be True for this flag to have an effect
- Returns:
Parsed result.
- Return type:
tuple
- buku.is_bad_url(url)[source]
Check if URL is malformed.
Note
This API is not bulletproof but works in most cases.
- Parameters:
url (str) – URL to scan.
- Returns:
True if URL is malformed, False otherwise.
- Return type:
bool
- buku.is_editor_valid(editor)[source]
Check if the editor string is valid.
- Parameters:
editor (str) – Editor string.
- Returns:
True if string is valid, else False.
- Return type:
bool
- buku.is_ignored_mime(url)[source]
Check if URL links to ignored MIME.
Note
Only a ‘HEAD’ request is made for these URLs.
- Parameters:
url (str) – URL to scan.
- Returns:
True if URL links to ignored MIME, False otherwise.
- Return type:
bool
- buku.is_int(string)[source]
Check if a string is a digit.
- stringstr
Input string to check.
- Returns:
True on success, False on exception.
- Return type:
bool
- buku.is_nongeneric_url(url)[source]
Returns True for URLs which are non-http and non-generic.
- Parameters:
url (str) – URL to scan.
- Returns:
True if URL is a non-generic URL, False otherwise.
- Return type:
bool
- buku.is_unusual_tag(tagstr)[source]
Identify unusual tags with word to comma ratio > 3.
- Parameters:
tagstr (str) – tag string to check.
- Returns:
True if valid tag else False.
- Return type:
bool
- buku.like_escape(s, c='`')
- buku.network_handler(url: str, http_head: bool = False) Tuple[str, str, str, int, int] [source]
Handle server connection and redirections.
Deprecated; use fetch_data() instead.
- Returns:
(title, description, tags, recognized mime, bad url)
- Return type:
tuple
- buku.parse_decoded_page(page)[source]
Fetch title, description and keywords from decoded HTML page.
- Parameters:
page (str) – Decoded HTML page.
- Returns:
(title, description, keywords).
- Return type:
tuple
- buku.parse_range(tokens: str | Sequence[str] | Set[str] | None, valid: Callable[[int], bool] | None = None) Set[int] | None [source]
Convert a token or sequence/set of token into a set of indices.
Raises a ValueError on invalid token. Returns None if passed None as tokens.
- Parameters:
tokens (str | str[] | str{}, optional) – String(s) containing an index (#), or a range (#-#), or a comma-separated list thereof.
valid ((int) -> bool, optional) – Additional check for invalid indices (default is None).
- Returns:
None if tokens is None, otherwise parsed indices as unordered set.
- Return type:
Optional[Set[int]]
- buku.parse_tags(keywords=[])[source]
Format and get tag string from tokens.
- Parameters:
keywords (list) – List of tags to parse. Default is empty list.
- Returns:
str – Comma-delimited string of tags.
DELIM (str) – If no keywords, returns the delimiter.
None – If keywords is None.
- buku.parse_temp_file_content(content)[source]
Parse and return temporary file content.
- Parameters:
content (str) – String of content.
- Returns:
(url, title, tags, comments)
url: URL to open title: string title to add manually tags: string of comma-separated tags to add manually comments: string description
- Return type:
tuple
- buku.prep_tag_search(tags: str) Tuple[List[str], str | None, str | None] [source]
Prepare list of tags to search and determine search operator.
- Parameters:
tags (str) – String list of tags to search.
- Returns:
- (list of formatted tags to search,
a string indicating query search operator (either OR or AND), a regex string of tags or None if ‘ - ‘ delimiter not in tags).
- Return type:
tuple
- buku.print_json_safe(resultset, single_record=False, field_filter=0)[source]
Prints json results and handles IOError
- Parameters:
resultset (list) – Search results from DB query.
single_record (bool) – If True, indicates only one record. Default is False.
field_filter (int) – Indicates format for displaying bookmarks. Default is 0 (“all fields”).
- Return type:
None
- buku.print_rec_with_filter(records, field_filter=0)[source]
Print records filtered by field.
User determines which fields in the records to display by using the –format option.
- Parameters:
records (list or sqlite3.Cursor object) – List of bookmark records to print
field_filter (int) – Integer indicating which fields to print. Default is 0 (“all fields”).
- buku.print_single_rec(row: BookmarkVar, idx: int = 0, columns: int = 0)[source]
Print a single DB record.
Handles both search results and individual record.
- Parameters:
row (tuple) – Tuple representing bookmark record data.
idx (int) – Search result index. If 0, print with DB index. Default is 0.
columns (int) – Number of columns to wrap comments to. Default is 0.
- buku.prompt(obj, results, noninteractive=False, deep=False, listtags=False, suggest=False, num=10)[source]
Show each matching result from a search and prompt.
- Parameters:
obj (BukuDb instance) – A valid instance of BukuDb class.
results (list) – Search result set from a DB query.
noninteractive (bool) – If True, does not seek user input. Shows all results. Default is False.
deep (bool) – Use deep search. Default is False.
listtags (bool) – If True, list all tags.
suggest (bool) – If True, suggest similar tags on edit and add bookmark.
num (int) – Number of results to show per page. Default is 10.
- buku.read_in(msg)[source]
A wrapper to handle input() with interrupts disabled.
- Parameters:
msg (str) – String to pass to to input().
- buku.regexp(expr, item)[source]
Perform a regular expression search.
- Parameters:
expr (regex) – Regular expression to search for.
item (str) – Item on which to perform regex search.
- Returns:
True if result of search is not None, else False.
- Return type:
bool
- buku.setcolors(args)[source]
Get colors from user and separate into ‘result’ list for use in arg.colors.
- Parameters:
args (str) – Color string.
- buku.setup_logger(LOGGER)[source]
Setup logger with color.
- Parameters:
LOGGER (logger object) – Logger to colorize.
- buku.show_taglist(obj)[source]
Additional prompt to show unique tag list.
- Parameters:
obj (BukuDb instance) – A valid instance of BukuDb class.
- buku.sigint_handler(signum, frame)[source]
Custom SIGINT handler.
Note
Neither signum nor frame are used in this custom handler. However, they are required parameters for signal handlers.
- Parameters:
signum (int) – Signal number.
frame (frame object or None.) –
- buku.strip_delim(s, delim=',', sub=' ')
- buku.taglist(ss)
- buku.taglist_str(s)
- buku.to_temp_file_content(url, title_in, tags_in, desc)[source]
Generate temporary file content string.
- Parameters:
url (str) – URL to open.
title_in (str) – Title to add manually.
tags_in (str) – Comma-separated tags to add manually.
desc (str) – String description.
- Returns:
Lines as newline separated string.
- Return type:
str
- Raises:
AttributeError – when tags_in is None.