Documentation of the lexigram-admin public API surface, stability tiers,
and deprecation policy.
Symbols in lexigram-admin are classified into one of three stability
tiers. Each tier has different guarantees about backward compatibility.
Public API that is guaranteed to remain backward-compatible within the
same major version. Breaking changes require a major version bump and
are announced at least one minor version in advance.
Changes follow this process:
Deprecation warning added (one minor version before removal).
Breaking change scheduled for next major version.
Migration guide published.
Public API that is still under active development. Breaking changes may
occur at any time without prior deprecation. Experimental features are
clearly marked in their docstrings and __init__.py exports.
Consumers should expect instability.
Feedback is encouraged to shape the final API.
Experimental features may be promoted to @stable or removed entirely.
Public API that is scheduled for removal. Deprecated symbols:
Emit a DeprecationWarning when accessed.
Document the replacement in their docstring.
Remain available for one minor version, then are removed at the next
major version.
Symbols prefixed with a leading underscore (_) are private and
not part of the public API . They may change or be removed without
notice. Consumers must not import them.
Symbols in _*.py module files follow the same rule — the underscore
module signals that all contents are internal.
Symbol Tier Notes Resource✅ stable Base class for admin resources ResourceConfig✅ stable Configuration dataclass for resources TableConfiguration✅ stable Table display config _validate_resource_name🔒 internal Private helper
Symbol Tier Notes SchemaField✅ stable Abstract base for all field types TextField✅ stable Text input field EmailField✅ stable Email field with validation SelectField✅ stable Dropdown / multi-select field BooleanField✅ stable Checkbox / toggle field DateField✅ stable Date picker field DateTimeField✅ stable DateTime picker field TimeField✅ stable Time picker field NumberField✅ stable Numeric input field TextareaField✅ stable Multi-line text field FileField🧪 experimental File upload (depends on lexigram-media) PasswordField✅ stable Masked password input ColorField✅ stable Color picker field TagsField🧪 experimental Tag input field ImageField🧪 experimental Image upload / display field URLField✅ stable URL input field PhoneField✅ stable Phone number field HiddenField✅ stable Hidden input field PlaceholderField✅ stable Read-only display field FieldValidator✅ stable Validator protocol FieldError✅ stable Field validation error type
Symbol Tier Notes IDataSource✅ stable Protocol for data access DataSourceBase✅ stable Abstract base for data sources SqlDataSource✅ stable SQL-backed data source QueryResult✅ stable Paginated query result QuerySpec✅ stable Immutable query specification PagedResult✅ stable Lightweight paginated result FilterOperator✅ stable Filter operator enum FilterCondition✅ stable Filter condition dataclass
Symbol Tier Notes Action✅ stable Abstract base for all actions RowAction✅ stable Action on a single record BulkAction✅ stable Action on multiple selected records HeaderAction✅ stable Action with no record context ActionGroup🧪 experimental Grouped action menu
Symbol Tier Notes Cluster✅ stable Navigation group dataclass
Symbol Tier Notes AbstractRelationManager✅ stable ABC for relation managers RelationManager🧪 experimental Concrete manager with inline CRUD
Symbol Tier Notes LayoutType✅ stable Enum: LIST, GRID, CALENDAR, KANBAN, etc. LayoutConfig✅ stable Layout configuration dataclass
Symbol Tier Notes AbstractRule✅ stable Base class for validation rules FieldError✅ stable Validation error type IsValidAdminEmail✅ stable Email validation rule StrongPassword✅ stable Password strength rule IsValidUsername✅ stable Username format rule (other concrete rules) ✅ stable See validation/rules.py
Symbol Tier Notes Command✅ stable Action command dataclass AdminProviderState🔒 internal Provider lifecycle state SystemSetting✅ stable Key-value setting dataclass AdminUser✅ stable Re-exported admin user type
Symbol Tier Notes (all middleware classes) 🔒 internal Registered by the framework, not for direct use
Symbol Tier Notes (all view classes) 🔒 internal Internal views, not for direct consumption
Symbol Tier Notes Page✅ stable Base class for custom admin pages
Symbol Tier Notes AdminBundleProvider✅ stable Provider for registering admin in container AdminModule✅ stable Module for configuring the admin panel
The canonical indicator of public API. Any symbol exported from a package’s
__init__.py is part of the public API surface:
from lexigram.admin.resources.base import Resource
Types that are consumed by external packages (or user code) should be
importable from the public path:
# ✅ Public — import from public path
from lexigram.admin.schema import TextField
# ❌ Internal — avoid deep paths
from lexigram.admin.schema.base import TextField
Public API docstrings include stability information:
Protocols decorated with @runtime_checkable (e.g., IDataSource) are
deliberately public — they are designed for third-party implementations.
The lifecycle of a public API symbol:
@experimental ──► released for feedback
@stable ◄─────────────────┘
Tested — unit and integration tests cover the feature.Documented — docstrings follow Google style; usage guide exists.Reviewed — API surface reviewed for consistency with existing patterns.Backward-compatible — signature is unlikely to need breaking changes.At least one minor release — the feature has been @experimental
for at least one minor version.
Symbol is marked @deprecated in its docstring.
Deprecation warning is emitted on access (via warnings.warn with
DeprecationWarning).
Replacement is documented in the docstring and the warning message.
Migration guide is published.
Event Version Feature marked @experimental X.Y.0 Feature marked @deprecated X.Y+1.0 Feature removed X.Y+2.0 (next major)
@deprecated ( "Use 'fields' list instead. See MIGRATION_FROM_TRIPLET.md" )
def __init__ ( self , * args , ** kwargs ):
"TextColumn is deprecated. Use TextField with "
"visible_in_list=True instead." ,
Security fixes may remove unsafe API without deprecation.Internal (_-prefixed) symbols may be removed at any time.@experimental symbols
├── AbstractRelationManager
