[dg] Rename PackageObject* -> PluginObject*

Author: smackesey

docs/docs/guides/labs/dg/configuring-dg.md

@@ -0,0 +1,36 @@
+---
+title: 'Configuring dg'
+sidebar_position: 500
+---
+
+import Preview from '@site/docs/partials/\_Preview.md';
+
+<Preview />
+
+`dg` is primarily configured using 
+
+
+
+## Default `dg` behavior (`uv run`)
+
+`dg` itself is installed globally and always executes in an isolated environment. However, many `dg` commands need to spawn subprocesses in environments scoped to specific projects. For example, when you run `dg list component-type` in a project directory, `dg` only lists the component types available in that project.
+
+When using `dg` with default settings, the Python subprocess is spawned after detecting a virtual environment in the project directory. This means that, rather than finding the first `python` executable on your shell `PATH`, it will instead use the Python executable from a locally detected virtual environment even if that virtual environment is not currently activated.
+
+By default, `dg` uses a special `uv` command called `uv run` for environment detection and command execution. `uv run` resolves a local virtual environment (`.venv` in an ancestor directory) before running a command, and additionally makes sure that the environment is up to date with the project's specified dependencies before running the command.
+
+`dg`'s use of `uv run` means you don't need to manage global shell state by activating and deactivating virtual environments during development. Instead, `dg` expects (and will scaffold for you) a `.venv` directory in the root of each project, and will use that virtual environment when executing commands (such as `dg scaffold defs` or `dg list component-type`) against that project.
+
+## Disabling use of `uv run`
+
+You can disable `dg`'s use of `uv run` by passing the `--no-use-dg-managed-environment` flag to `dg` commands. This will cause `dg` to still try to resolve local virtual environments by looking up the ancestor tree for `.venv`, but instead launch Python processes directly rather than going through `uv run`.
+
+If you want to opt out of virtual environment detection entirely and just use your ambient Python environment (system Python or an activated virtual env), you should also (a) set `--no-require-local-venv`, and (b) ensure there are no `.venv` directories in
+the ancestor tree of your project.
+
+:::info
+
+Disabling `uv` integration with `--no-use-dg-managed-environment` will
+currently disable the `dg cache`. This will make some operations noticeably slower.
+
+:::

examples/docs_snippets/docs_snippets/guides/components/index/17-dg-list-component-types.txt

@@ -2,7 +2,7 @@ dg list component-type
 
 Using /.../jaffle-platform/.venv/bin/dagster-components
 ┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ Package       ┃ Objects                                                                                              ┃
+┃ Plugin        ┃ Objects                                                                                              ┃
 ┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
 │ dagster       │ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓ │
 │               │ ┃ Symbol                                                      ┃ Summary          ┃ Features        ┃ │

examples/docs_snippets/docs_snippets/guides/components/index/7-dg-list-component-types.txt

@@ -1,7 +1,7 @@
 dg list component-type
 
 ┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ Package ┃ Objects                                                                                                    ┃
+┃ Plugin  ┃ Objects                                                                                                    ┃
 ┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
 │ dagster │ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓ │
 │         │ ┃ Symbol                                                      ┃ Summary            ┃ Features            ┃ │

examples/docs_snippets/docs_snippets/guides/components/index/8-dg-list-component-types.txt

@@ -2,7 +2,7 @@ dg list component-type
 
 Using /.../jaffle-platform/.venv/bin/dagster-components
 ┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ Package       ┃ Objects                                                                                              ┃
+┃ Plugin        ┃ Objects                                                                                              ┃
 ┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
 │ dagster       │ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓ │
 │               │ ┃ Symbol                                                      ┃ Summary          ┃ Features        ┃ │

examples/docs_snippets/docs_snippets/guides/components/shell-script-component/3-dg-list-component-types.txt

@@ -2,7 +2,7 @@ dg list component-type
 
 Using /.../my-component-library/.venv/bin/dagster-components
 ┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ Package              ┃ Objects                                                                                       ┃
+┃ Plugin               ┃ Objects                                                                                       ┃
 ┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
 │ dagster              │ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓ │
 │                      │ ┃ Symbol                                                      ┃ Summary      ┃ Features     ┃ │

python_modules/dagster/dagster/components/cli/list.py

@@ -2,7 +2,7 @@
 from typing import Literal, Optional, Union
 
 import click
-from dagster_shared.serdes.objects import PackageObjectKey
+from dagster_shared.serdes.objects import PluginObjectKey
 from dagster_shared.serdes.objects.definition_metadata import (
     DgAssetCheckMetadata,
     DgAssetMetadata,
@@ -160,7 +160,7 @@ def list_definitions_command(
 
 def _load_library_objects(
     entry_points: bool, extra_modules: tuple[str, ...]
-) -> dict[PackageObjectKey, object]:
+) -> dict[PluginObjectKey, object]:
     objects = {}
     if entry_points:
         objects.update(discover_entry_point_package_objects())
@@ -171,7 +171,7 @@ def _load_library_objects(
 
 def _load_component_types(
     entry_points: bool, extra_modules: tuple[str, ...]
-) -> dict[PackageObjectKey, type[Component]]:
+) -> dict[PluginObjectKey, type[Component]]:
     return {
         key: obj
         for key, obj in _load_library_objects(entry_points, extra_modules).items()

python_modules/dagster/dagster/components/cli/scaffold.py

@@ -2,7 +2,7 @@
 from typing import Optional
 
 import click
-from dagster_shared.serdes.objects import PackageObjectKey
+from dagster_shared.serdes.objects import PluginObjectKey
 from pydantic import TypeAdapter
 
 from dagster.components.component_scaffolding import scaffold_object
@@ -30,7 +30,7 @@ def scaffold_object_command(
     json_params: Optional[str],
     scaffold_format: str,
 ) -> None:
-    key = PackageObjectKey.from_typename(typename)
+    key = PluginObjectKey.from_typename(typename)
     obj = load_package_object(key)
 
     if json_params:

python_modules/dagster/dagster/components/core/defs_module.py

@@ -5,7 +5,7 @@
 from pathlib import Path
 from typing import Any, Optional, TypeVar
 
-from dagster_shared.serdes.objects import PackageObjectKey
+from dagster_shared.serdes.objects import PluginObjectKey
 from dagster_shared.yaml_utils import parse_yaml_with_source_positions
 from pydantic import BaseModel, ConfigDict, TypeAdapter
 
@@ -245,7 +245,7 @@ def get_component(cls, context: ComponentLoadContext) -> Component:
 
         # find the component type
         type_str = context.normalize_component_type_str(component_file_model.type)
-        key = PackageObjectKey.from_typename(type_str)
+        key = PluginObjectKey.from_typename(type_str)
         obj = load_package_object(key)
         if not isinstance(obj, type) or not issubclass(obj, Component):
             raise DagsterInvalidDefinitionError(

python_modules/dagster/dagster/components/core/package_entry.py

@@ -5,7 +5,7 @@
 from collections.abc import Iterable, Sequence
 from types import ModuleType
 
-from dagster_shared.serdes.objects import PackageObjectKey
+from dagster_shared.serdes.objects import PluginObjectKey
 
 from dagster._core.errors import DagsterError
 from dagster.components.utils import format_error_message
@@ -25,7 +25,7 @@ def get_entry_points_from_python_environment(group: str) -> Sequence[importlib.m
         return importlib.metadata.entry_points().get(group, [])
 
 
-def discover_entry_point_package_objects() -> dict[PackageObjectKey, object]:
+def discover_entry_point_package_objects() -> dict[PluginObjectKey, object]:
     """Discover package entries registered in the Python environment via the
     `dg_library` entry point group.
 
@@ -34,7 +34,7 @@ def discover_entry_point_package_objects() -> dict[PackageObjectKey, object]:
     component types and is loaded by default. Other entry points resolve to various sets of test
     component types. This method will only ever load one builtin package.
     """
-    objects: dict[PackageObjectKey, object] = {}
+    objects: dict[PluginObjectKey, object] = {}
     entry_points = get_entry_points_from_python_environment(DG_LIBRARY_ENTRY_POINT_GROUP)
 
     for entry_point in entry_points:
@@ -54,16 +54,16 @@ def discover_entry_point_package_objects() -> dict[PackageObjectKey, object]:
                 f"Value expected to be a module, got {root_module}."
             )
         for name, obj in get_package_objects_in_module(root_module):
-            key = PackageObjectKey(name=name, namespace=entry_point.value)
+            key = PluginObjectKey(name=name, namespace=entry_point.value)
             objects[key] = obj
     return objects
 
 
-def discover_package_objects(modules: Sequence[str]) -> dict[PackageObjectKey, object]:
-    objects: dict[PackageObjectKey, object] = {}
+def discover_package_objects(modules: Sequence[str]) -> dict[PluginObjectKey, object]:
+    objects: dict[PluginObjectKey, object] = {}
     for extra_module in modules:
         for name, obj in get_package_objects_in_module(importlib.import_module(extra_module)):
-            key = PackageObjectKey(name=name, namespace=extra_module)
+            key = PluginObjectKey(name=name, namespace=extra_module)
             objects[key] = obj
     return objects
 
@@ -77,7 +77,7 @@ def get_package_objects_in_module(
             yield attr, value
 
 
-def load_package_object(key: PackageObjectKey) -> object:
+def load_package_object(key: PluginObjectKey) -> object:
     module_name, attr = key.namespace, key.name
     try:
         module = importlib.import_module(module_name)

python_modules/dagster/dagster/components/core/snapshot.py

@@ -3,8 +3,8 @@
 
 from dagster_shared.serdes.objects.package_entry import (
     ComponentFeatureData,
-    PackageObjectKey,
-    PackageObjectSnap,
+    PluginObjectKey,
+    PluginObjectSnap,
     ScaffoldTargetTypeData,
 )
 
@@ -43,7 +43,7 @@ def _get_scaffold_target_type_data(scaffolder: Scaffolder) -> ScaffoldTargetType
     )
 
 
-def get_package_entry_snap(key: PackageObjectKey, obj: object) -> PackageObjectSnap:
+def get_package_entry_snap(key: PluginObjectKey, obj: object) -> PluginObjectSnap:
     type_data = []
     owners = []
     tags = []
@@ -56,7 +56,7 @@ def get_package_entry_snap(key: PackageObjectKey, obj: object) -> PackageObjectS
     if isinstance(scaffolder, Scaffolder):
         type_data.append(_get_scaffold_target_type_data(scaffolder))
     summary, description = _get_summary_and_description(obj)
-    return PackageObjectSnap(
+    return PluginObjectSnap(
         key=key,
         summary=summary,
         owners=owners,