Copy groups and subparsers per Parser instance

The Group/Parser instances written in a class body were registered by
the metaclass and shared by every instance of that Parser class: a
second parse_args() — on another instance — overwrote the first
instance's group and subcommand values.

Parser.__init__ now clones the declared member tree (recursively for
nested groups and subparser trees) so every Parser instance owns its
parsed state. The class-level instances become pristine prototypes.

Because every binding gets its own copy, assigning one Group instance
to several attributes is now supported — each location keeps
independent parsed state. The previous "referenced more than once"
error is narrowed to the only unclonable shape: a cyclic group tree
(detected at construction time, with a parse-time backstop for cycles
wired into instance mappings after __init__).

Behavior changes:
- parser.group is no longer the class-body instance; code that kept a
  module-level reference to a Group/subparser instance must read
  values via the parser instance.
- Reusing one Group instance across attributes works instead of
  raising (the copies share the prototype's title/prefix, so an
  explicit prefix= would still produce conflicting CLI flags).
- Cycle errors fire at Parser construction instead of parse_args().

Author: mosquito

CLAUDE.md

@@ -97,9 +97,11 @@ Naming follows the attribute path:
 - JSON/TOML: nested objects/tables
 
 `Group(prefix=...)` overrides only the CLI/env segment for that group;
-config section names always follow the attribute path. Reusing the
-same Group instance in two places raises `ArgclassError` (instantiate
-a separate Group per attribute).
+config section names always follow the attribute path. Class-body
+Group/subparser instances are prototypes: every Parser instance works
+on its own copies, so one Group instance may be bound to several
+attributes (each binding is an independent copy). Only cyclic group
+trees raise `ArgclassError`.
 
 ### Subcommands
 

argclass/parser.py

@@ -1,5 +1,6 @@
 """Core parser classes for argclass."""
 
+import copy
 import os
 import weakref
 from abc import ABCMeta
@@ -568,6 +569,52 @@ def __init__(
         self._defaults: Mapping[str, Any] = defaults or {}
 
 
+def _group_reuse_error(path: str) -> ArgclassError:
+    return ArgclassError(
+        "Group instance is referenced more than once in the parser "
+        f"tree (current path: {path}): the group tree must not "
+        "contain cycles.",
+        hint="Remove the self-reference; a group cannot (directly or "
+        "indirectly) contain itself.",
+    )
+
+
+def _clone_group_tree(
+    group: Group,
+    ancestors: set[int],
+    attr_path: tuple[str, ...],
+) -> Group:
+    """Copy ``group`` and its nested groups for one parser instance.
+
+    The group instances registered by the metaclass live on the class
+    body and would otherwise be shared by every instance of the Parser
+    class — a second ``parse_args()`` on another instance would
+    overwrite the first one's values.
+
+    Because every occurrence gets its own copy, assigning one Group
+    instance to several attributes is fine — each binding becomes an
+    independent copy. ``ancestors`` holds the ids along the current
+    path only, so the recursion rejects exactly the unclonable case:
+    a group that (directly or indirectly) contains itself.
+    """
+    if id(group) in ancestors:
+        raise _group_reuse_error(".".join(attr_path))
+    ancestors.add(id(group))
+    try:
+        clone = copy.copy(group)
+        nested: dict[str, Group] = {}
+        for child_name, child in group.__argument_groups__.items():
+            child_clone = _clone_group_tree(
+                child, ancestors, attr_path + (child_name,)
+            )
+            setattr(clone, child_name, child_clone)
+            nested[child_name] = child_clone
+        clone.__argument_groups__ = MappingProxyType(nested)
+        return clone
+    finally:
+        ancestors.discard(id(group))
+
+
 ParserType = TypeVar("ParserType", bound="Parser")
 
 
@@ -737,6 +784,43 @@ def __init__(
         self._parser_kwargs = kwargs
         self._used_env_vars: set[str] = set()
         self._used_secret_env_vars: set[str] = set()
+        self._materialize_members()
+
+    def _materialize_members(self) -> None:
+        """Give this parser instance its own copies of the declared
+        groups and subparsers.
+
+        The instances collected by the metaclass live on the class
+        body and are shared by every instance of this Parser class;
+        parsing through them would let a second instance overwrite
+        the first one's values. Copying them per instance
+        (recursively, for nested groups and subparser trees) makes
+        every Parser instance own its parsed state, while the
+        class-level prototypes stay pristine.
+        """
+        cls = type(self)
+
+        ancestors: set[int] = set()
+        groups: dict[str, Group] = {}
+        for name, group in cls.__argument_groups__.items():
+            clone = _clone_group_tree(group, ancestors, (name,))
+            setattr(self, name, clone)
+            groups[name] = clone
+        self.__argument_groups__ = MappingProxyType(groups)
+
+        subparsers: dict[str, Any] = {}
+        for name, subparser in cls.__subparsers__.items():
+            sub_clone = copy.copy(subparser)
+            # The shallow copy still references the prototype's own
+            # member clones and env-var bookkeeping; rebuild them.
+            sub_clone._materialize_members()
+            sub_clone._used_env_vars = set(subparser._used_env_vars)
+            sub_clone._used_secret_env_vars = set(
+                subparser._used_secret_env_vars
+            )
+            setattr(self, name, sub_clone)
+            subparsers[name] = sub_clone
+        self.__subparsers__ = MappingProxyType(subparsers)
 
     @property
     def current_subparser(self) -> "AbstractParser | None":
@@ -880,15 +964,11 @@ def _fill_group(
         destinations: DestinationsType,
         visited: set[int],
     ) -> None:
+        # Backstop: instance trees are validated at construction time
+        # by ``_clone_group_tree``; this catches cycles wired into the
+        # per-instance mappings after ``__init__``.
         if id(group) in visited:
-            raise ArgclassError(
-                "Group instance is referenced more than once in the parser "
-                f"tree (current path: {'.'.join(attr_path)}). Reusing a "
-                "single Group instance across attributes is not supported "
-                "because state would be shared between locations.",
-                hint="Instantiate a new Group for each attribute, or "
-                "subclass Group to define a dedicated type.",
-            )
+            raise _group_reuse_error(".".join(attr_path))
         visited.add(id(group))
 
         section = ".".join(attr_path)

docs/groups.md

@@ -386,12 +386,14 @@ assert parser.database.port == 5432
 Rejected forms raise `ArgumentDefinitionError` immediately when the
 parser class is defined, with a hint suggesting the correct form.
 
-### Reusing a group instance is an error
-
-Passing the same `Group` instance to two different attributes raises
-`ArgclassError`, because that group's parsed state would otherwise be
-shared between locations. Instantiate a separate group per attribute,
-or subclass `Group` to define a dedicated type:
+### Reusing a group instance
+
+Group instances in a class body are prototypes — every parser
+instance works on its own copies, so the same `Group` instance may be
+bound to several attributes and each binding keeps independent parsed
+state. Separate instances per attribute remain the clearest style
+(and are required when the attributes need different `title`/`prefix`
+options):
 
 <!--- name: test_groups_nested_separate_instances --->
 ```python

docs/pitfalls.md

@@ -211,11 +211,12 @@ class Parser(argclass.Parser):
 
 ### Reusing a Group instance across attributes
 
-Each `Group` instance owns the parsed state for one location in the
-parser tree. Assigning the **same instance** to two attributes raises
-`ArgclassError`, because parsed values would otherwise be shared
-between both locations.
+Group instances written in a class body are **prototypes**: every
+parser instance works on its own copies. That makes assigning the
+same instance to several attributes safe — each binding becomes an
+independent copy with its own parsed state:
 
+<!--- name: test_pitfall_group_instance_reuse --->
 ```python
 import argclass
 
@@ -225,26 +226,26 @@ class Credentials(argclass.Group):
 shared = Credentials()
 
 class Parser(argclass.Parser):
-    primary = shared      # OK on its own — single binding
-    secondary = shared    # Together with `primary`, raises ArgclassError
-                          # at parse_args time (same instance bound twice)
-```
-
-A single attribute bound to an externally-created Group is fine; the
-error only fires when the **same instance** is reachable through two
-or more attributes at parse time.
-
-Create a separate instance for each attribute instead:
+    primary = shared
+    secondary = shared    # fine: each binding gets its own copy
 
-```python
-class Parser(argclass.Parser):
-    primary = Credentials()      # RIGHT - distinct instances
-    secondary = Credentials()
+parser = Parser()
+parser.parse_args([
+    "--primary-username", "alice",
+    "--secondary-username", "bob",
+])
+assert parser.primary.username == "alice"
+assert parser.secondary.username == "bob"
 ```
 
-Using the same `Group` **class** twice (with different `Group()` calls)
-is fully supported — only sharing one already-constructed instance is
-disallowed.
+Keep in mind that the copies inherit the prototype's `title`,
+`description`, and `prefix`. A reused instance with an explicit
+`prefix=` would produce conflicting CLI flags — give each attribute
+its own instance when they need different options.
+
+The only forbidden shape is a **cycle** — a group that (directly or
+indirectly) contains itself raises `ArgclassError` at parser
+construction time.
 
 ---
 
@@ -297,14 +298,12 @@ The same applies to names of Parser API methods (`parse_args`,
 define on your own parser classes: an argument cannot shadow them.
 :::
 
-:::{warning}
-Group and subparser attributes are **class-level singletons**: every
-instance of the same Parser class shares the same Group and subparser
-objects. A second `parse_args()` — whether on the same parser instance
-or on another instance of the same class — overwrites the group and
-subcommand values produced by the first one. When you need independent
-results (e.g. parsing several argv sets side by side), keep each
-result before the next parse, or define separate Parser classes.
+:::{note}
+Every Parser instance works on its **own copies** of the declared
+groups and subparsers: the instances written in the class body are
+just prototypes. Parsing one parser instance never affects another
+one, and the prototypes stay pristine. Re-parsing the *same* parser
+instance overwrites its previous values, as expected.
 
 <!--- name: test_pitfall_shared_groups --->
 ```python
@@ -318,11 +317,12 @@ class CLI(argclass.Parser):
 
 first = CLI()
 second = CLI()
-assert first.db is second.db  # the same Group object!
+assert first.db is not second.db  # independent copies
 
 first.parse_args(["--db-host", "from-first"])
 second.parse_args(["--db-host", "from-second"])
-assert first.db.host == "from-second"  # overwritten by the later parse
+assert first.db.host == "from-first"  # not affected by the later parse
+assert second.db.host == "from-second"
 ```
 :::
 

tests/test_audit_fixes.py

@@ -516,6 +516,101 @@ class B(A):
         assert b.LIMIT == 5
 
 
+class TestPerInstanceState:
+    """Fix 6: groups and subparsers are copied per Parser instance,
+    so parsing one instance never mutates another (or the class-level
+    prototypes)."""
+
+    def test_groups_independent_across_instances(self):
+        class CLI(argclass.Parser):
+            db = SharedDB()
+
+        first = CLI()
+        second = CLI()
+        assert first.db is not second.db
+
+        first.parse_args(["--db-host", "from-first"])
+        second.parse_args(["--db-host", "from-second"])
+        assert first.db.host == "from-first"
+        assert second.db.host == "from-second"
+
+    def test_class_prototype_stays_pristine(self):
+        class CLI(argclass.Parser):
+            db = SharedDB()
+
+        prototype = CLI.__argument_groups__["db"]
+        cli = CLI()
+        cli.parse_args(["--db-host", "parsed"])
+        assert cli.db is not prototype
+        with pytest.raises(AttributeError):
+            prototype.host
+
+    def test_nested_groups_independent(self):
+        class Credentials(argclass.Group):
+            username: str = "admin"
+
+        class Endpoint(argclass.Group):
+            credentials: Credentials = Credentials()
+
+        class CLI(argclass.Parser):
+            endpoint: Endpoint = Endpoint()
+
+        first = CLI()
+        second = CLI()
+        first.parse_args(["--endpoint-credentials-username", "alice"])
+        second.parse_args(["--endpoint-credentials-username", "bob"])
+        assert first.endpoint.credentials.username == "alice"
+        assert second.endpoint.credentials.username == "bob"
+
+    def test_subparsers_independent_across_instances(self):
+        class CLI(argclass.Parser):
+            serve = SharedServe()
+
+        first = CLI()
+        second = CLI()
+        assert first.serve is not second.serve
+
+        first.parse_args(["serve", "--port", "1111"])
+        second.parse_args(["serve", "--port", "2222"])
+        assert first.serve.port == 1111
+        assert second.serve.port == 2222
+        assert first.current_subparser is first.serve
+        assert second.current_subparser is second.serve
+
+    def test_subparser_groups_independent(self):
+        class Sub(argclass.Parser):
+            db = SharedDB()
+
+        class CLI(argclass.Parser):
+            sub = Sub()
+
+        first = CLI()
+        second = CLI()
+        first.parse_args(["sub", "--db-host", "h1"])
+        second.parse_args(["sub", "--db-host", "h2"])
+        assert first.sub.db.host == "h1"
+        assert second.sub.db.host == "h2"
+
+    def test_reparse_same_instance_overwrites(self):
+        class CLI(argclass.Parser):
+            db = SharedDB()
+
+        cli = CLI()
+        cli.parse_args(["--db-host", "one"])
+        cli.parse_args(["--db-host", "two"])
+        assert cli.db.host == "two"
+
+    def test_group_options_preserved_on_copy(self):
+        class CLI(argclass.Parser):
+            db = SharedDB(prefix="dbx", defaults={"host": "preset"})
+
+        cli = CLI()
+        cli.parse_args([])
+        assert cli.db.host == "preset"
+        cli.parse_args(["--dbx-host", "cli-value"])
+        assert cli.db.host == "cli-value"
+
+
 class TestPathTypeUnchanged:
     """Sanity: Path defaults and types keep working end to end."""