Refactor package management terminology and add new reference pages

codekiln · codekiln · commit bfb50cb0a116 · 2025-03-02T07:59:36.000-05:00
- Rename "Python" to "Py" across multiple pages
- Create new pages for Package Management, Package Manager, and Software Library
- Update journal entries and references to use consistent terminology
- Add comprehensive uv package management how-to guide
- Improve documentation structure for package-related concepts
diff --git a/journals/2025_02_16.md b/journals/2025_02_16.md
@@ -27,7 +27,7 @@
 				- has a "generator" for cursor
 				- #Example - [[smithery.ai/smithery.ai/server/mcp-obsidian]] [Obsidian Reader | Smithery](https://smithery.ai/server/mcp-obsidian)
 					- ![image.png](../assets/image_1739708199177_0.png)
-- #Python
+- #Py
 	- Sebastian Raschka started recommending [[uv]] in setup guide - #Tip
 		- via [[Person/Sebastian Raschka/TwitX]] here:
 			- {{tweet https://x.com/rasbt/status/1890842082756935853}}
diff --git a/journals/2025_03_02.md b/journals/2025_03_02.md
@@ -1,6 +1,9 @@
 ## #AI
+	- [[AI Knowledge Gardening]]
+		-
 - ## #[[CLI Craftsmanship]]
-	- ## [[uv/How To/Add a Package to pyproject.toml]]
+	- #Filed
+		- [[uv/How To/Add a Package to pyproject.toml]]
 - ## #Cool People
 	- #Filed
 		- [[Person/Daniele Procida]]
@@ -9,11 +12,13 @@
 		- [[Diataxis/How To]]
 		- [[Diataxis/How To/Create a How To]]
 		- [[Ubuntu/Blog/24/12/Docs dev and design for technical authors]]
+			- {{embed ((67c44872-7f65-463f-94d9-6ffda609eb7a))}}
 - ## #[[Knowledge Gardening]]
 	- ## #Wordsmithing
 		- #Filed
 			- [[AI Knowledge Gardening]]
 			- [[CursorAI Project Rule GitHub Link]]
 			- [[CursorAI Project Rule Local Link]]
 			- [[CLI Craftsmanship]]
-			- [[Knowledge Gardening]]
+			- [[Knowledge Gardening]]
+			- [[Package Management]]
diff --git a/pages/AI___ES___25___ws___1___Building Agents with Model Context Protocol.md b/pages/AI___ES___25___ws___1___Building Agents with Model Context Protocol.md
@@ -445,7 +445,7 @@ tags:: [[Anthropic/Model Context Protocol]]
 				- Metadata includes **versions**, **protocol types** (`stdio`, `sse`), and **URLs**.
 				- Supports **multiple package registries** (`npm`, `pypi`, etc.)
 		- my #notes
-			- this lets us have something like npm, pypi, [[Package Manager]]s for mcp
+			- this lets us have something like npm, pypi, [[Package/Manager]]s for mcp
 			- how do you determine whether it's sse or stdio
 			- who built it, is it verified, did [[Shopify]] bless this server?
 			- "this is coming, it's going to be great"
diff --git a/pages/CursorAI___Technique___Project Rules___GitHub Gist Auto-Updater.md b/pages/CursorAI___Technique___Project Rules___GitHub Gist Auto-Updater.md
@@ -20,7 +20,7 @@
 					- Show status messages for install/update/current
 	- ## Future variations
 		- could consider making a generic script that would detect any .mdc files in the gist and apply to all of them, so that installer could be reused
-		- it would probably be better if there was a standard [[Package Manager]] for cursor rules though
+		- it would probably be better if there was a standard [[Package/Manager]] for cursor rules though
 		- could also consider a [[GitHub Repo Template]] as a way to create one's own **stdlib**, as per [[Person/Geoffrey Huntley/Blog/25/02/You are using Cursor AI incorrectly...]]
 	- ### Benefits for Sharing Cursor Rules
 		- Version control through GitHub Gists
diff --git a/pages/Package___Management.md b/pages/Package___Management.md
@@ -0,0 +1,15 @@
+alias:: [[Package Management]]
+tags:: [[Term]]
+
+- # Package Management
+	- The set of tools that enable installing [[Software Libraries]] in a consistent way.
+	- More generally, the set of tooling and conventions that enable importing modular content in a systematic way.
+	- #Examples of [[Package Managers]]
+		- [[Python]]
+			- [[uv]]
+			- [[pip]]
+			- [[Poetry]]
+		- [[Rust]]
+			- [[cargo]]
+		- [[Java]]
+			- [[Maven]]
diff --git a/pages/Package___Manager.md b/pages/Package___Manager.md
@@ -0,0 +1 @@
+alias:: [[Package Manager]], [[Package Managers]]
diff --git a/pages/Py.md b/pages/Py.md
@@ -0,0 +1 @@
+alias:: [[Python]]
diff --git a/pages/Software___Library.md b/pages/Software___Library.md
@@ -0,0 +1 @@
+alias:: [[Software Libraries]]
diff --git a/pages/Ubuntu___Blog___24___12___Docs dev and design for technical authors.md b/pages/Ubuntu___Blog___24___12___Docs dev and design for technical authors.md
@@ -1,7 +1,7 @@
 created-by:: [[Person/Daniele Procida]]
 
 - # [Documentation, development and design for technical authors | Ubuntu](https://ubuntu.com/blog/documentation-development-and-design-for-technical-authors)
-	- #Quotes
-		- ## A merciless kind of light
-		- Everyone knows the experience of having a fine idea, that when it has to be spelled out in words, suddenly looks a bit less splendid.
-		- This is what documentation does. Documentation is a clear and merciless kind of light. Under its harsh scrutiny, many aspects of a product can look ugly, or clunky, or disjointed.
+	- ## A merciless kind of light - #Quote from [[Person/Daniele Procida]]
+	  id:: 67c44872-7f65-463f-94d9-6ffda609eb7a
+		- > Everyone knows the experience of having a fine idea, that when it has to be spelled out in words, suddenly looks a bit less splendid.
+		- > This is what documentation does. **Documentation is a clear and merciless kind of light**. Under its harsh scrutiny, many aspects of a product can look ugly, or clunky, or disjointed.
diff --git a/pages/VSCode___Docs___Languages___Python___Tutorial.md b/pages/VSCode___Docs___Languages___Python___Tutorial.md
@@ -20,7 +20,7 @@ readwise-link:: https://read.readwise.io/new/read/01jfz94w9xygdp5gx50req7srh
 	  :END:
 	- DONE import into #Readwise/Reader [Linting Python in Visual Studio Code](https://code.visualstudio.com/docs/python/linting) [[VSCode/Docs/Python/Linting]]
 	  id:: 676d1d2b-6ad5-4baa-9a2e-218ad2c419ce
-- DONE Run [[Python]] code
+- DONE Run [[Py]] code
   id:: 676d1d19-1ea4-42bd-b1b2-844f44aa63b3
   :LOGBOOK:
   CLOCK: [2024-12-26 Thu 04:11:58]--[2024-12-26 Thu 04:19:30] =>  00:07:32
@@ -31,7 +31,7 @@ readwise-link:: https://read.readwise.io/new/read/01jfz94w9xygdp5gx50req7srh
 		  gitp-acolyte ✘ Me@Home  ~/dev/gitpa  ↱ cc/04-host-n-dist/03-ai-ep-yml  /Users/Me/.pyenv/versions/3.13.1/envs/gitp-acolyte/bin/python /Users/Me/dev/gitpa/gitp-acolyte/gitp_acolyte/hello.py
 		  Roll a dice!
 		  ```
-	- ## four ways to run #Python in #VSCode
+	- ## four ways to run #Py in #VSCode
 	  id:: 676d1dfa-f9d4-4335-be68-fcd95e3fe89a
 	  card-last-interval:: -1
 	  card-repeats:: 1
diff --git a/pages/VSCode___Docs___Python___Testing.md b/pages/VSCode___Docs___Python___Testing.md
@@ -1,4 +1,4 @@
-# DONE [Testing Python in Visual Studio Code](https://code.visualstudio.com/docs/python/testing) - #Python #Pytest [[Software/Testing]]
+# DONE [Testing Python in Visual Studio Code](https://code.visualstudio.com/docs/python/testing) - #Py #Pytest [[Software/Testing]]
 id:: 6777cb12-88af-4ac9-a143-2a0c4ef1f93c
 :LOGBOOK:
 CLOCK: [2025-01-03 Fri 06:34:13]--[2025-01-15 Wed 03:26:46] =>  284:52:33
diff --git a/pages/VSCode___Proj___24t3___LearnVSCode.md b/pages/VSCode___Proj___24t3___LearnVSCode.md
@@ -40,7 +40,7 @@ created-by-template:: [[Logseq/Template/Project/Page]]
 			  :LOGBOOK:
 			  CLOCK: [2024-12-19 Thu 03:19:51]--[2024-12-20 Fri 03:11:24] =>  23:51:33
 			  :END:
-			- DONE create a milestone for learning #Python in #VSCode: ((676c215b-e6e1-42a5-8842-69dfea383749))
+			- DONE create a milestone for learning #Py in #VSCode: ((676c215b-e6e1-42a5-8842-69dfea383749))
 			  id:: 676a7b3a-475a-4d9c-a42a-0df0c87d0b96
 			  :LOGBOOK:
 			  CLOCK: [2024-12-25 Wed 10:14:02]--[2024-12-25 Wed 10:36:49] =>  00:22:47
@@ -59,7 +59,7 @@ created-by-template:: [[Logseq/Template/Project/Page]]
 			  id:: 67692054-752a-4cd6-a890-dcbfeb10b9e5
 				- TODO create [[Diataxis/How To]] browse from a diff to the file to edit it using a #Keyshort in [[VSCode/Git]]
 				  id:: 6763ee82-a86e-4962-83af-5ce7a61f34d0
-			- #### TODO create advanced #Python #VSCode milestones
+			- #### TODO create advanced #Py #VSCode milestones
 				- TODO create a milestone for **Refactoring Python**
 				- TODO create a milestone for **Docker Python** - using interpreter inside of docker-compose - *note, should not include Dev Containers*
 				- TODO create a milestone for **Dev Container Python** for creating a [Dev Container](https://code.visualstudio.com/docs/devcontainers/containers) for python
diff --git a/pages/mise.md b/pages/mise.md
@@ -11,7 +11,7 @@ created-by:: [[Person/Jeff Dickey]]
 			- **before one begins cooking, a professional chef should have all their utensils and ingredients ready to go and in their place**
 	- use `mise.toml` describes consistent way to setup and interact with projects across languages
 	- ### 3 categories of usage for `mise`
-		- `1`: installs [[NodeJS]], [[Python]], [[Terraform]]
+		- `1`: installs [[NodeJS]], [[Py]], [[Terraform]]
 			- specify versions of tools per project
 			- `mise` supports [hundreds](https://mise.jdx.dev/plugins.html) of dev tools
 		- `2`: manages [[EnvVar]]s
diff --git a/pages/uv___How To___Add a Package to pyproject.toml.md b/pages/uv___How To___Add a Package to pyproject.toml.md
@@ -1,2 +1,116 @@
--
-- # TODO
+tags:: [[uv]], [[Py/pyproject.toml]], [[Package/Management]], [[Diataxis/How To]]
+
+- # How To Add a Package to pyproject.toml with uv
+	- ## Overview
+		- This guide walks you through adding a package dependency to your Python project's pyproject.toml file using the uv tool.
+		- It's for Python developers who are working on projects managed with uv and need to add new dependencies.
+	- ## Prerequisites
+		- [uv installed](https://github.com/astral-sh/uv) on your system
+		- An existing Python project with a pyproject.toml file
+		- Project directory structure initialized with `uv init` or containing a valid pyproject.toml
+	- ## Steps
+		- ### 1. Navigate to Your Project Directory
+			- Open a terminal or command prompt
+			- Change to your project's root directory where the pyproject.toml file is located
+			- Example: `cd path/to/your/project`
+		- ### 2. Add a Package Using the uv Command
+			- Run the `uv add` command followed by the package name
+			- Basic syntax: `uv add <package-name>`
+			- Example: `uv add ruff`
+			- This will:
+				- Create a virtual environment at .venv if one doesn't exist
+				- Add the package to your project's dependencies in pyproject.toml
+				- Install the package in your project's virtual environment
+				- Update the uv.lock file with the exact resolved versions
+		- ### 3. Specify a Version Constraint (Optional)
+			- To add a specific version or version range, use the following syntax:
+			- `uv add <package-name>@<version-constraint>`
+			- Examples:
+				- Exact version: `uv add ruff@0.5.4`
+				- Version range: `uv add ruff@">=0.5.0,<0.6.0"`
+				- Minimum version: `uv add ruff@">=0.5.0"`
+		- ### 4. Add Multiple Packages (Optional)
+			- You can add multiple packages in a single command by listing them
+			- Example: `uv add ruff pytest black`
+		- ### 5. Add Development Dependencies (Optional)
+			- To add a package as a development dependency, use the `--dev` flag
+			- Example: `uv add --dev pytest`
+			- This adds the package to the `project.optional-dependencies.dev` section in pyproject.toml
+		- ### 6. Verify the Package Was Added
+			- Check your pyproject.toml file to confirm the dependency was added
+			- The package should appear in the `dependencies` list under the `[project]` section
+			- Example of updated pyproject.toml:
+			  ```toml
+			  [project]
+			  name = "your-project"
+			  version = "0.1.0"
+			  description = "Your project description"
+			  dependencies = [
+			     "ruff>=0.5.0",
+			  ]
+			  ```
+	- ## Using uv with #mise
+		- ### Overview
+			- [mise](https://mise.jdx.dev/) is a dev tool manager that can manage Python versions and tools like uv
+			- Using mise with uv provides a seamless way to manage both Python versions and packages
+		- ### Setting Up mise with uv
+			- #### 1. Install mise
+				- Install mise using the official installer: `curl https://mise.run | sh`
+				- Activate mise in your shell: `eval "$(~/.local/bin/mise activate bash)"` (adjust for your shell)
+			- #### 2. Configure Python with mise
+				- Create a `.mise.toml` file in your project root:
+				  ```toml
+				  [tools]
+				  python = "3.11"  # Or your preferred version
+				  ```
+				- Or use the command line: `mise use python@3.11`
+			- #### 3. Install uv with mise
+				- Add uv to your mise configuration:
+				  ```toml
+				  [tools]
+				  python = "3.11"
+				  
+				  [tasks.install-uv]
+				  description = "Install uv package manager"
+				  run = "pip install uv"
+				  ```
+				- Run the task: `mise run install-uv`
+			- #### 4. Create a Task for Adding Packages
+				- Add a task to your `.mise.toml` for adding packages:
+				  ```toml
+				  [tasks.add-pkg]
+				  description = "Add a package to pyproject.toml"
+				  run = "uv add $@"
+				  ```
+				- Use it with: `mise run add-pkg ruff`
+				- #### [[My Notes]] on this technique
+					- *Why would one want to do this? Perhaps because #mise affords one the opportunity to set a common schema of tasks and reuse them across package managers. If one created similarly named tasks in each language that mise manages, then this `add-pkg` could be that interface.*
+		- ### Benefits of Using mise with uv
+			- Consistent Python versions across team members
+			- Project-specific Python version management
+			- Simplified workflow with mise tasks for common uv commands
+			- Easier onboarding for new team members
+		- ### Local Configuration
+			- For personal preferences, use `.mise.local.toml` (add to .gitignore)
+			- Example for personal uv configuration:
+			  ```toml
+			  [env]
+			  UV_CACHE_DIR = "~/.cache/uv-custom"
+			  
+			  [tasks.my-add-pkg]
+			  description = "Add a package with my preferred settings"
+			  run = "uv add --dev $@"
+			  ```
+	- ## Troubleshooting
+		- If you see `Error: No pyproject.toml found`: Make sure you're in the correct directory or initialize a project with `uv init`
+		- If you see `Error: Package not found`: Check the package name for typos or verify it exists on PyPI
+		- If installation fails with version conflicts: Try using a different version constraint or check compatibility with your other dependencies
+		- If the virtual environment isn't created: Run `uv venv` to manually create it
+		- If using mise and commands aren't found: Ensure mise is activated with `eval "$(mise activate)"`
+		- If mise tasks aren't working: Check your `.mise.toml` syntax and try running with `MISE_DEBUG=1`
+	- ## Related
+		- [[uv/How To/Initialize a Project]]
+		- [[uv/How To/Remove a Package]]
+		- [[uv/How To/Update Dependencies]]
+		- [[uv/Reference/pyproject.toml]]
+		- [[mise/How To/Manage Python Projects]]

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+alias:: [[Package Manager]], [[Package Managers]]`