pnbp 0.9.0rc1__tar.gz

pnbp-0.9.0rc1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2021 prettynb
+Copyright (c) 2026 Outside Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pnbp-0.9.0rc1/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pnbp
+Version: 0.9.0rc1
+Summary: Python tools for parsing and querying wiki-linked, tagged Markdown notebooks.
+Author: prettynb
+Maintainer: Outside Labs
+License-Expression: MIT
+Project-URL: Homepage, https://outside-labs.com
+Project-URL: Repository, https://github.com/outside-labs/pretty-notebook
+Project-URL: Documentation, https://github.com/outside-labs/pretty-notebook/tree/main/docs
+Project-URL: Issues, https://github.com/outside-labs/pretty-notebook/issues
+Keywords: markdown,notes,wikilinks,knowledge-management
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: markdown>=3.3.4
+Requires-Dist: requests>=2.26
+Requires-Dist: rich>=10.6
+Dynamic: license-file
+
+pnbp = **"pretty notebook parser"**
+
+--- 
+
+**pnbp** provides programmatic access to a **notebook** via :
+- **[> pnbp/models](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/pnbp_models.md)** : **models and methods**. 
+    - access notes and their individual (regex established) components in the python repl, scripts, and your own shell commands. 
+- **[> pnbp/commands](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/pnbp_commands.md)** : **shell commands**. 
+    - run pre-defined function against a notebook in the terminal directly, or, scheduled.
+
+\--- 
+
+a pretty **notebook** is the collection of markdown files in a specific directory.
+a pretty **note** is a single .md file within the notebook directory.
+
+**links** ( \[\[link\]\] , !\[\[link.jpg\]\] ), **tags** ( \#tag ), **codeblocks** ( \`\`\`py print("Hello World")\`\`\` ), and **urls** ( \[goog\]\(https://google.com) ) are the main components outside of additional [render syntax](https://daringfireball.net/projects/markdown/syntax) of a .md note using an extended linking and tagging markdown. 
+
+https://obsidian.md/ is the best example of this in action. 
+
+--- 
+
+#### quickstart guide : 
+
+--- 
+
+##### (0) -> ```pip install pnbp```
+
+##### (1) -> [access via the Notebook model](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/pnbp_models.md)
+
+##### (2) -> [cli commands](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/pnbp_commands.md)
+
+##### (3) -> [web application / api](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/web.md) *(experimental; not supported for public deployment in 0.9.0rc1)*
+
+##### (4) -> [“pnano”](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/pnano.md) *(experimental/unsupported in 0.9.0rc1)*
+
+--- 
+
+##### (-1) -> **git clone** the repo.
+
+```bash
+pip uninstall pnbp
+git clone https://github.com/outside-labs/Pretty-Notebook/ pnbp
+cd pnbp/
+pip install . # pyproject.toml defined requirements 
+pip install --editable . # pnbp/cli.py defined “pnbp command”s 
+```
+
+--- 
+
+##### (2) -> set **environment variables**.
+
+| var | desc | e.g. |
+| :--: | :--: | :--: |
+| **NOTE_PATH** | the full directory path of your notebook | ```echo 'export NOTE_PATH="/users/alice/notebook"' >> ~/.zshrc``` |
+| **IMG_PATH** | (optional entirely; set here or in pnbp_settings.json) | ```echo 'export IMG_PATH="$NOTE_PATH/imgs"' >> ~/.zshrc``` | 
+| **HTML_PATH** | (optional entirely; useful debug w/ Pretty-Notebook/apps/web api; set here, in pnbp_settings.json, or not at all.) | ```echo 'export HTML_PATH="$NOTE_PATH/html"' >> ~/.zshrc``` | 
+| **NOTE_NESTED** | (optional; default=*"flat"*) => *"single"*, *"recurs"*, *"all"*,  | ... |
+| **PNBP_SETTINGS** | (optional) => **"off"** to ignore using a NOTE_PATH/pnbp_settings.json  | ```echo 'export PNBP_SETTINGS="off"' >> ~/.zshrc``` |
+
+**NOTE_NESTED**  
+- *"flat"* - by default, **pnbp** assumes that every .md note exist within the base directory level of **NOTE\_PATH**/.
+- *"single"* - if you want **pnbp** to search for .md notes within additional (non-hidden) directory level up.
+- *"recurs"* - if you want .md notes to be found through all (non-hidden) directory levels up.
+- *"all"* - if you want even hidden (non- .git, .obsidian) directories traversed recursively up.
+
+**PNBP_SETTINGS**  
+- without ```PNBP_SETTINGS="off"```, "**NOTE\_PATH/pnbp_settings.json**" will be nagged for.
+- **Notebook** can generate one at the python prompt that you can edit later -> 
+
+( ... on **Windows**? Environment Variable(s) can be set [here](https://docs.oracle.com/en/database/oracle/machine-learning/oml4r/1.5.1/oread/creating-and-modifying-environment-variables-on-windows.html#GUID-DD6F9982-60D5-48F6-8270-A27EC53807D0). Also, recall that in most places you'll also need to escape the "```\```" within any **path** strings (e.g. ```"IMG_PATH": "\\Users\\alice\\notebook\\imgs"```) used; the drive letter (e.g. ```"D:\\Media\imgs"```) is optional if it's your **\%HOMEDRIVE\%**. )
+
+--- 
+
+##### (3) -> **access your notes in python3.11+ !**
+
+
+```py
+>>> import pnbp
+>>> nb = pnbp.Notebook()
+... 
+```
+
+--- 
+
+<p align=center>
+  <img src=https://raw.githubusercontent.com/outside-labs/Pretty-Notebook/main/docs/IMG_pnbp.png alt=Pretty-Notebook width=200>
+</p>

pnbp-0.9.0rc1/README.md

@@ -0,0 +1,19 @@
+# Pretty-Notebook
+
+A Python toolkit and FastAPI publisher for interconnected Markdown notebooks.
+
+[Documentation](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/pnbp.md)
+
+```mermaid
+graph BT
+	id1[(Notebook)]
+	id2[(Note)] --> id1
+	Link --> id2
+	Url --> id2
+	CodeBlock --> id2
+	Tag --> id2
+```
+
+<p align=center>
+  <img src=https://raw.githubusercontent.com/outside-labs/Pretty-Notebook/main/docs/IMG_pnbp.png alt=Pretty-Notebook width=200>
+</p>

pnbp-0.9.0rc1/docs/pnbp.md

@@ -0,0 +1,87 @@
+pnbp = **"pretty notebook parser"**
+
+--- 
+
+**pnbp** provides programmatic access to a **notebook** via :
+- **[> pnbp/models](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/pnbp_models.md)** : **models and methods**. 
+    - access notes and their individual (regex established) components in the python repl, scripts, and your own shell commands. 
+- **[> pnbp/commands](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/pnbp_commands.md)** : **shell commands**. 
+    - run pre-defined function against a notebook in the terminal directly, or, scheduled.
+
+\--- 
+
+a pretty **notebook** is the collection of markdown files in a specific directory.
+a pretty **note** is a single .md file within the notebook directory.
+
+**links** ( \[\[link\]\] , !\[\[link.jpg\]\] ), **tags** ( \#tag ), **codeblocks** ( \`\`\`py print("Hello World")\`\`\` ), and **urls** ( \[goog\]\(https://google.com) ) are the main components outside of additional [render syntax](https://daringfireball.net/projects/markdown/syntax) of a .md note using an extended linking and tagging markdown. 
+
+https://obsidian.md/ is the best example of this in action. 
+
+--- 
+
+#### quickstart guide : 
+
+--- 
+
+##### (0) -> ```pip install pnbp```
+
+##### (1) -> [access via the Notebook model](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/pnbp_models.md)
+
+##### (2) -> [cli commands](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/pnbp_commands.md)
+
+##### (3) -> [web application / api](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/web.md) *(experimental; not supported for public deployment in 0.9.0rc1)*
+
+##### (4) -> [“pnano”](https://github.com/outside-labs/Pretty-Notebook/blob/main/docs/pnano.md) *(experimental/unsupported in 0.9.0rc1)*
+
+--- 
+
+##### (-1) -> **git clone** the repo.
+
+```bash
+pip uninstall pnbp
+git clone https://github.com/outside-labs/Pretty-Notebook/ pnbp
+cd pnbp/
+pip install . # pyproject.toml defined requirements 
+pip install --editable . # pnbp/cli.py defined “pnbp command”s 
+```
+
+--- 
+
+##### (2) -> set **environment variables**.
+
+| var | desc | e.g. |
+| :--: | :--: | :--: |
+| **NOTE_PATH** | the full directory path of your notebook | ```echo 'export NOTE_PATH="/users/alice/notebook"' >> ~/.zshrc``` |
+| **IMG_PATH** | (optional entirely; set here or in pnbp_settings.json) | ```echo 'export IMG_PATH="$NOTE_PATH/imgs"' >> ~/.zshrc``` | 
+| **HTML_PATH** | (optional entirely; useful debug w/ Pretty-Notebook/apps/web api; set here, in pnbp_settings.json, or not at all.) | ```echo 'export HTML_PATH="$NOTE_PATH/html"' >> ~/.zshrc``` | 
+| **NOTE_NESTED** | (optional; default=*"flat"*) => *"single"*, *"recurs"*, *"all"*,  | ... |
+| **PNBP_SETTINGS** | (optional) => **"off"** to ignore using a NOTE_PATH/pnbp_settings.json  | ```echo 'export PNBP_SETTINGS="off"' >> ~/.zshrc``` |
+
+**NOTE_NESTED**  
+- *"flat"* - by default, **pnbp** assumes that every .md note exist within the base directory level of **NOTE\_PATH**/.
+- *"single"* - if you want **pnbp** to search for .md notes within additional (non-hidden) directory level up.
+- *"recurs"* - if you want .md notes to be found through all (non-hidden) directory levels up.
+- *"all"* - if you want even hidden (non- .git, .obsidian) directories traversed recursively up.
+
+**PNBP_SETTINGS**  
+- without ```PNBP_SETTINGS="off"```, "**NOTE\_PATH/pnbp_settings.json**" will be nagged for.
+- **Notebook** can generate one at the python prompt that you can edit later -> 
+
+( ... on **Windows**? Environment Variable(s) can be set [here](https://docs.oracle.com/en/database/oracle/machine-learning/oml4r/1.5.1/oread/creating-and-modifying-environment-variables-on-windows.html#GUID-DD6F9982-60D5-48F6-8270-A27EC53807D0). Also, recall that in most places you'll also need to escape the "```\```" within any **path** strings (e.g. ```"IMG_PATH": "\\Users\\alice\\notebook\\imgs"```) used; the drive letter (e.g. ```"D:\\Media\imgs"```) is optional if it's your **\%HOMEDRIVE\%**. )
+
+--- 
+
+##### (3) -> **access your notes in python3.11+ !**
+
+
+```py
+>>> import pnbp
+>>> nb = pnbp.Notebook()
+... 
+```
+
+--- 
+
+<p align=center>
+  <img src=https://raw.githubusercontent.com/outside-labs/Pretty-Notebook/main/docs/IMG_pnbp.png alt=Pretty-Notebook width=200>
+</p>

pnbp-0.9.0rc1/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pnbp"
+version = "0.9.0rc1"
+description = "Python tools for parsing and querying wiki-linked, tagged Markdown notebooks."
+readme = "docs/pnbp.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+
+authors = [
+    { name = "prettynb" },
+]
+maintainers = [
+    { name = "Outside Labs" },
+]
+
+keywords = [
+    "markdown",
+    "notes",
+    "wikilinks",
+    "knowledge-management",
+]
+
+dependencies = [
+    "click>=8.0",
+    "markdown>=3.3.4",
+    "requests>=2.26",
+    "rich>=10.6",
+]
+
+[project.urls]
+Homepage = "https://outside-labs.com"
+Repository = "https://github.com/outside-labs/pretty-notebook"
+Documentation = "https://github.com/outside-labs/pretty-notebook/tree/main/docs"
+Issues = "https://github.com/outside-labs/pretty-notebook/issues"
+
+[project.scripts]
+pnbp = "pnbp.cli:cli"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["pnbp*"]
+namespaces = false
+
+[tool.pytest.ini_options]
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+testpaths = ["tests"]
+filterwarnings = [
+    "error",
+    "ignore:'crypt' is deprecated and slated for removal in Python 3.13:DeprecationWarning:passlib\\.utils",
+]

pnbp-0.9.0rc1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pnbp-0.9.0rc1/src/pnbp/__init__.py

@@ -0,0 +1 @@
+from .models import Notebook

pnbp-0.9.0rc1/src/pnbp/cli.py

@@ -0,0 +1,251 @@
+import os 
+import subprocess
+import sys
+import inspect
+
+import click
+import requests
+
+from .commands import collect
+from .commands import commit
+from .commands import correct
+from .commands import code
+from .commands import graph
+from .commands import pprint
+from .commands import subl
+from .commands import tasks
+
+from .models import Notebook
+from .helpers import arrow_call
+
+
+
+@click.group()
+def cli():
+	pass
+
+
+
+""" Pretty-Notebook/apps/web api connection commands:
+"""
+def _publish_notebook(notebook, **kwargs):
+	"""Run publication with concise CLI reporting for transport failures."""
+	try:
+		return notebook.post_commits_to_web_api(**kwargs)
+	except requests.RequestException as error:
+		raise click.ClickException(f'Publication failed: {error}') from error
+
+
+@cli.command()
+def commit_html():
+	""" if note contains #public, -> HTML_PATH/.html 
+		(for local debugging when running remote server 
+		and not a concurrent localhost instance...)
+	"""
+	# ^^ docstring == help message
+	nb = Notebook()
+	nb.write_commits_to_local_html()
+
+
+@cli.command()
+@click.option(
+	'--prune',
+	is_flag=True,
+	help='Remove every remote page absent from this notebook after successful uploads.',
+)
+@click.option(
+	'--refresh-images',
+	is_flag=True,
+	help='Resend referenced images even when their names already exist remotely.',
+)
+def commit_remote(prune, refresh_images):
+	""" if note contains #public, -> 
+		selective update POST to .../apps/web api
+		@ {API_BASE}/api/publishment
+	"""
+	nb = Notebook()
+	_publish_notebook(nb, prune=prune, refresh_images=refresh_images)
+
+
+@cli.command()
+@click.option(
+	'--prune',
+	is_flag=True,
+	help='Remove every remote page absent from this notebook after successful uploads.',
+)
+@click.option(
+	'--refresh-images',
+	is_flag=True,
+	help='Resend referenced images even when their names already exist remotely.',
+)
+def commit_local(prune, refresh_images):
+	""" commit -> localhost .../apps/web instance
+	""" # a convenience command
+	nb = Notebook()
+	nb.API_BASE = 'http://127.0.0.1:8000'
+	_publish_notebook(nb, prune=prune, refresh_images=refresh_images)
+
+
+@cli.command()
+def commit_stage():
+	""" *only* print commit- changes against nb.API_BASE
+		to the terminal (staging view)
+	"""
+	nb = Notebook()
+	_publish_notebook(nb, stage_only=True)
+
+
+@cli.command()
+@click.option('--local', is_flag=True, default=False, help="post to localhost instead of the configured API_BASE")
+def commit_settings(local):
+	""" commit nb.NOTE_PATH/pnbp_settings.json -> the Pretty-Notebook/apps/web api .../web_settings.json 
+	"""
+	nb = Notebook()
+	
+	if local:
+		nb.API_BASE = 'http://127.0.0.1:8000'
+		
+	nb.web_settings_post()
+
+
+@cli.command()
+def git_clone_pnbp_web():
+	""" command to clone from github to ./pnbp_web/
+	"""
+	cmd = ["git", "clone", "--filter=blob:none", 
+			"--sparse", "--depth", "1", "--single-branch", 
+			"--branch", "main", "https://github.com/outside-labs/Pretty-Notebook.git",
+			"pnbp-web"]
+
+	cmd2 = ["git", "-C", "pnbp-web", "sparse-checkout", "set", "apps/web"]
+		
+	op = subprocess.run(cmd,capture_output=True)
+		
+	click.echo(op.stderr) # git outputs stdout to stderr
+
+	wp = subprocess.run(cmd2, capture_output=True)
+	
+	click.echo(wp.stderr) 
+
+
+
+""" building click.commands out of 
+	the (imported above) local /commands/ package
+"""
+def _create_command(func):
+	""" effectively writes a :
+
+		```@click.command()
+			def outer_act_cmd():
+				_outer_act_cmd()
+		```	
+
+	where I had issues passing live parameters 
+	and chaining command calls in click otherwise.
+	
+	As actively wrapping here (vs calling _outer_act_cmd()),
+	has the nice feature of passing the _cmd's docstring to the --help info.
+
+	:param func: 
+	"""
+	func.__name__ = func.__name__.lstrip('_')
+
+	cmd = cli.command()
+
+	if 'note' in inspect.signature(func).parameters.keys():
+		# prove it : 
+		func = click.option(
+			'--fuzzy',
+			is_flag=True,
+			help='explicitly accept the closest matching note name',
+		)(func)
+		func = click.option('-n', '--note', type=str, help='the name of a note', required=True)(func)
+
+	func = arrow_call(func)
+
+	return cmd(func)
+
+
+def create_command(func):
+	""" actually instantiating the command
+		and specifically setattr-ing here after built is necessary
+
+	:param func: 
+	"""
+	c = _create_command(func)
+	setattr(sys.modules[__name__], func.__name__.lstrip('_'), c)
+
+
+def create_commands(module, _all=False):
+	""" 
+
+	:param module: an commands/module.py imported above
+	:param _all: _all=True will create a command from all leading underscore _func_name of module
+	"""
+	for k,v in module.__dict__.items():
+		# print(k) # _func's name...
+		if _all:
+			if (inspect.isfunction(v) 
+			and k.startswith('_')
+			and v.__module__ == module.__name__): # ignore if imported 
+				create_command(v)
+		else:
+			# leave open for additional bool switches
+			pass
+
+
+
+def create_all_commands():
+	""" main function for building imported module commands 
+		and tacking them onto the click.group(), & module local() name cli
+
+	"""
+	create_commands(collect, _all=True)
+
+	# Imported collection helpers are excluded by create_commands() so that
+	# module scans do not accidentally register unrelated imports. Register the
+	# five intended collection commands explicitly.
+	create_command(collect._collect_code_blocked)
+	create_command(collect._collect_tasks_note)
+	create_command(collect._collect_public_graph)
+	create_command(collect._collect_all_graphs)
+	create_command(collect._collect_subl_projs)
+
+	create_commands(commit, _all=True)
+
+	create_commands(correct, _all=True)
+
+
+	create_command(code._extract_code_blocks)
+	create_command(code._extract_all_code_blocks)
+
+	create_command(graph._create_link_graph)
+	create_command(graph._create_tag_graph)
+	create_command(graph._delete_all_graph_dash_name)
+
+	create_command(pprint._pprint)
+
+	create_command(subl._subl_init)
+
+	create_command(tasks._task_settle)
+
+
+
+	
+
+
+
+
+
+
+
+
+# -> required to call here (pre-main) for pyproject.toml / 
+# pip install to recognize dynamically created commands
+create_all_commands()
+
+if __name__ == '__main__':
+	cli()
+	
+
+