.. _cookbook_advanced_pyrogue_patterns:

=================
Advanced Patterns
=================

Advanced PyRogue usage commonly includes:

- Device method overrides and composition patterns
- Complex ``RemoteVariable`` bit mappings
- Computed ``LinkVariable`` dependencies

Design Principles
=================

- Keep base ``Device`` classes predictable; isolate special behavior in narrow
  overrides.
- Favor declarative variable definitions over implicit runtime mutation.
- Keep link-variable dependency graphs shallow and well documented.

Common Failure Modes
====================

- Hidden side effects inside command callbacks.
- Overloaded variables that mix control intent and status reporting.
- Circular or fragile link-variable dependencies.

Validation Checklist
====================

- Commands are deterministic for the same input state.
- Variable update flows are understandable from docs and code together.
- Unit and range semantics are explicitly documented.

Starting points:

- :doc:`/pyrogue_tree/core/device`
- :doc:`/pyrogue_tree/core/remote_variable`
- :doc:`/pyrogue_tree/core/link_variable`

API reference:

- :doc:`/api/python/pyrogue/device`
- :doc:`/api/python/pyrogue/remotevariable`
- :doc:`/api/python/pyrogue/linkvariable`