माइग्रेशन गाइड

यह पेज starlette-admin रिलीज़ों के बीच upgrade instructions collect करता है। जिस वर्शन से आप upgrade कर रहे हैं, उससे match करने वाले section पर जाएँ।

0.17.x से 1.0.0

यह रिलीज़ starlette-admin के internals refactor करती है और new features का बड़ा set introduce करती है। High-level API largely unchanged रहते हुए भी, सबसे महत्त्वपूर्ण update list page rendering का rewrite है। हमने DataTables को server-rendered table के पक्ष में हटा दिया है। बाकी ज़्यादातर updates renames या minor signature changes हैं।

यह guide हर breaking change को उसी क्रम में cover करता है जिसमें आप उन्हें सबसे पहले encounter करने की संभावना रखते हैं। प्रत्येक section पुराने API को उसके replacement के साथ compare करता है। यदि आपका implementation basics या light customizations (जैसे एक Admin instance, कुछ ModelView subclasses, fields, और searchable_fields) पर टिका है, तो आपकी migration शायद केवल Requirements और The Admin constructor sections तक सीमित रहेगी, साथ में कुछ renames.

पुराने list page के customizations सबसे अधिक ध्यान माँगते हैं। DataTables options और JavaScript render functions का कोई direct equivalent नहीं है; उन्हें server-side templates पर port करना होगा (DataTables Removal देखें)।

What's new

नीचे outlined breaking changes से परे, इस रिलीज़ में:

• Native list tables: DataTables हटाकर built-in, server-rendered implementation आई है। Table state अब पूरी तरह URL-driven है — page, filter, और sort configurations तुरंत shareable और bookmarkable.
• Filters: Nested AND/OR filter builder DataTables SearchBuilder की जगह लेता है। Filters field types से derive होते हैं और pure Python में पूरी तरह extensible. JavaScript की ज़रूरत के बिना filter class लिख सकते हैं।
• Import and Server-Side Export: CSV, JSON, Excel, आदि से per-row error reporting के साथ data import करें, और client-side DataTables buttons की जगह server-side exporters (CSV, JSON, Excel, PDF आदि) उपयोग करें।
• Events: before_create, after_edit_committed, after_login, और various action events जैसे lifecycle hooks की सदस्यता लें।
• Themes और Plugins: Custom aesthetics और behaviors package/reuse करें। जल्दी शुरुआत के लिए Cookiecutter templates भी उपलब्ध हैं।
• Widgets and Dashboards: StatWidget, ChartWidget, TableWidget, आदि से index pages और custom views बनाएँ।
• Form Layout: Create/edit forms को rows, columns, fieldsets, और tabs से logically arrange करें।
• Inline Edit: List page से ही single field edit करें।
• Inline Forms: Parent form के भीतर related models को InlineModelView से edit करें।
• Other Enhancements: Flash messages, OAuth login, एक Tortoise ORM backend, new fields (ComputedField, SlugField, UUIDField, IPAddressField), field-level validators, और किसी भी field पर clipboard copy functionality.
• Logging: Package अब internally starlette_admin namespace के अंतर्गत log करता है, default silent. Request routing, middleware, और permission decisions console में देखने के लिए Admin(debug=True) pass करें या starlette_admin.logging.configure_logging() कॉल करें — migration के दौरान विशेष रूप से उपयोगी।
• Expanded Test Coverage: Test suite अब substantially बड़ी है, जिसमें admin interface के critical workflows validate करने वाले Playwright end-to-end tests शामिल हैं।
• Lighter Package: PyPI पर published package size ~50% कम हुई है।

आवश्यकताएँ

• Python Support: Python 3.11 या newer चाहिए। Python 3.9 और 3.10 support हट गया है।
• Core Dependencies: itsdangerous अब core dependency है, admin cookies (CSRF tokens और flash messages) sign करने के लिए।

• New Optional Extras:

  Extra	Enables
  starlette-admin[email]	EmailField server-side validation via email-validator
  starlette-admin[pdf]	PDF export via reportlab
  starlette-admin[s3]	S3 file storage via aiobotocore
  starlette-admin[tinymce]	TinyMCEEditorField HTML sanitization via nh3
  starlette-admin[i18n]	Translations via babel (unchanged)

• Beanie Backend: Beanie 2.0+ चाहिए।

• Odmantic Backend: हट गया। यदि आप उस पर depend करते हैं, तो starlette-admin<=0.17.1 पर रहें और issue खोलकर interest दिखाएँ; पर्याप्त demand होने पर support फिर जोड़ा जा सकता है।

Admin कंस्ट्रक्टर

# Before
admin = Admin(engine, statics_dir="statics")

# After
admin = Admin(engine, static_dir="statics", secret_key=os.environ["ADMIN_SECRET_KEY"])

• statics_dir rename होकर static_dir हुआ।
• secret_key सेट करें। यह key CSRF और flash-message cookies sign करती है। Omitted होने पर startup पर random key generate होती है (development के लिए ठीक), पर signed values हर restart और multiple workers में invalidate हो जाएँगी। Production में stable secret always pass करें।
• logo_url, login_logo_url, और favicon_url अब callable (request) -> str | None accept करते हैं। यह AdminConfig द्वारा पहले दी जाने वाली per-request branding replace करता है।
• New optional parameters: theme, plugins, additional_loaders, import_config, और export_config.
• SQLAlchemy specifics: पहला argument अब session_provider है। वह Engine या AsyncEngine accept करता है, अब sessionmaker या async_sessionmaker भी। मौजूदा Admin(engine) calls continue करते रहेंगे।
• timezone_config का default None के बजाय TimezoneConfig() है। Datetimes अब default रूप से viewer के local timezone में display होते हैं। Raw values retain करने के लिए timezone_config=None pass करें।

Renamed view identifiers

Views के लिए naming convention अब unified है। अपने ModelView constructors और class attributes उसी अनुसार update करें:

# Before
admin.add_view(PostView(Post, identity="post", name="Post", label="Posts"))

# After
admin.add_view(PostView(Post, key="post", display_name="Post", menu_label="Posts"))

ध्यान दें कि Link और DropDown भी label के बजाय menu_label उपयोग करते हैं।

DataTables removal

List page अब DataTables का उपयोग नहीं करता। पहले उसे configure करने वाले attributes पूरी तरह removed हैं:

यदि आपने पहले custom JavaScript render functions या DataTables plugins लिखे थे, तो उन्हें list_template overrides में port करें। हर field अब अपना list cell सीधे templates/fields/list/*.html से render करता है।

Actions

Batch action handlers अब primary keys की list के बजाय एक ActionSelection object receive करते हैं। इससे नए "select all matching" banner — current filter से match करने वाली हर row को client side पर materialize किए बिना target करने वाला — support मिलता है।

# Before
@action(name="publish", text="Publish")
async def publish_action(self, request: Request, pks: List[Any]) -> str:
    for article in await self.find_by_pks(request, pks):
        ...
    return f"{len(pks)} articles were published"


# After
@action(name="publish", text="Publish")
async def publish_action(self, request: Request, selection: ActionSelection) -> None:
    for article in await selection.rows():
        ...
    flash(request, f"{await selection.count()} articles were published")

• selection.rows(), selection.pks(), और selection.count() जैसे methods target rows lazily resolve करते हैं। यह तब भी लागू है जब user ने rows individually check की हों और तब भी जब all matching rows select की हों।
• selection.is_select_all, selection.filters, और selection.q जैसी properties operation को single bulk query के रूप में push down करने देती हैं।
• Success message string return करना flash messages से replace हुआ है।
• Row action handlers अपनी original (request, pk) signature retain करते हैं।
• New @action options: header, allow_empty_selection, dedicated_button, modal_size, और per-request form callables.

Authentication

starlette_admin/auth.py module अब starlette_admin.auth package है। starlette_admin.auth से existing imports continue करते रहेंगे, पर provider contract बदल गया है।

# Before
class MyAuthProvider(AuthProvider):
    async def login(self, username, password, remember_me, request, response):
        request.session.update({"username": username})
        return response

    async def logout(self, request, response):
        request.session.clear()
        return response

    async def is_authenticated(self, request) -> bool:
        request.state.user = my_users_db.get(request.session.get("username"))
        return request.state.user is not None

    def get_admin_user(self, request) -> AdminUser:
        return AdminUser(username=request.state.user["name"])

    def get_admin_config(self, request) -> AdminConfig:
        return AdminConfig(app_title="My Admin")


# After
class MyAuthProvider(AuthProvider):
    async def login(self, username, password, remember_me, request):
        if username in my_users_db:
            request.session.update({"username": username})
            return None  # default redirect (`next` param or admin index)
        raise LoginFailed("Invalid username or password")

    async def logout(self, request):
        request.session.clear()

    async def authenticate(self, request) -> AdminUser | None:
        user = my_users_db.get(request.session.get("username"))
        return AdminUser(username=user["name"]) if user else None

• Methods is_authenticated, get_admin_user, और get_admin_config एक single authenticate(request) -> AdminUser | None method में merge हो गई हैं। None return unauthenticated state दर्शाता है।
• login और logout methods prepared response receive या return नहीं करते। Default redirect के लिए None return करें, या behavior override करने के लिए custom Response return करें।
• AdminConfig removed है। Per-request titles और logos को Admin instance के logo_url और login_logo_url के callable form से handle करें।
• Built-in OAuthProvider OAuth2/OIDC login flows box से बाहर handle करता है।
• login_not_required decorator unchanged रहता है।

Export and Import

Exports client-side DataTables buttons से server-side streaming endpoints पर चले गए हैं। Import functionality पूरी तरह नई है, और ExportType अब मौजूद नहीं है।

# Before
from starlette_admin import ExportType


class PostView(ModelView):
    export_types = [ExportType.CSV, ExportType.EXCEL]
    export_fields = ["id", "title"]


# After
class PostView(ModelView):
    exporters = ["csv", "xlsx"]
    importers = ["csv", "json"]
    exclude_fields_from_export = ["content"]
    exclude_fields_from_import = ["id"]

• export_types अब exporters है। यह format names या BaseExporter instances की list accept करता है। Supported built-ins: csv, json, tsv, xlsx, ods, html, yaml, और pdf. csv/json के अलावा formats को tablib चाहिए, PDF को pdf extra.
• importers format names या BaseImporter instances की list accept करता है। Supported built-ins: csv, tsv, json, yaml, xlsx, xls, ods, dbf, और html. csv, tsv, json के अलावा formats को tablib चाहिए।
• export_fields (include list) replace होकर exclude_fields_from_export (exclude list) हुआ। यह बाकी exclude_fields_from_* attributes की naming convention से match करता है।
• Fields individually भी exclude_from_export और exclude_from_import accept करते हैं।
• Global limits Admin instance पर ExportConfig और ImportConfig से configure करें। Details के लिए Export & Import documentation देखें।

Custom fields and template overrides

Field templates reorganize हो गए हैं। यदि आप built-in templates override करते हैं या custom fields ship करते हैं, तो paths update करें:

# Before
@dataclass
class RatingField(BaseField):
    display_template: str = "displays/rating.html"
    form_template: str = "forms/rating.html"
    render_function_key: str = "rating"


# After
@dataclass
class RatingField(BaseField):
    detail_template: str = "fields/detail/rating.html"
    form_template: str = "fields/form/rating.html"
    list_template: str = "fields/list/rating.html"

Explore करने लायक new per-field capabilities: validators, filters, default, hooks (getter, formatter, parser), copy_to_clipboard, और arbitrary metadata के लिए एक extra dictionary. अधिक जानकारी के लिए Custom Fields documentation देखें।

CustomView

CustomView class अब template_path और methods accept नहीं करती। Simple pages widgets से बनाएँ। Full control चाहने वाले pages के लिए CustomView subclass करके routes सीधे declare करें।

# Before
admin.add_view(CustomView(label="Home", path="/home", template_path="home.html"))

# After: widget-based page
admin.add_view(
    CustomView(
        menu_label="System Status",
        path="/status",
        widget=StatWidget(title="Pending jobs", value_callback=count_pending_jobs),
    )
)


# After: full control
class HomeView(CustomView):
    menu_label = "Home"
    path = "/home"

    @route("")
    async def index(self, request: Request) -> Response:
        return self.templates.TemplateResponse(request=request, name="home.html")

@route decorator किसी भी view को extra endpoints expose करने देता है — JSON chart data या webhooks जैसी requirements के लिए।

Custom backends

यदि आपने custom datasource के विरुद्ध BaseModelView implement किया है, तो updated data-access contract ध्यान में रखें:

# Before
async def find_all(self, request, skip=0, limit=100, where=None, order_by=None): ...
async def count(self, request, where=None): ...


# After
async def find_all(
    self, request, skip=0, limit=100, q=None, sorts=None, filters=None
): ...
async def count(self, request, q=None, filters=None): ...

• String-typed where parameter split होकर q (full-text search terms के लिए) और filters (filter builder द्वारा दिया गया typed FilterGroup tree) हो गया।
• order_by parameter (पहले "field direction" strings की list) अब sorts है — (field_name, direction) tuples की list लेता है।
• हर backend अब field types को filter implementations से map करने वाला filter registry ship करता है। Full contract और working example के लिए Custom Backend documentation देखें।

Behavior changes to review

• Timezones: Datetimes default रूप से viewer के local timezone में render होते हैं (Admin Constructor section का timezone_config note देखें)।
• URL State: List state अब URL में रहती है। पिछले versions के bookmarked admin URLs default list states पर पहुँचेंगे, क्योंकि saved DataTables states migrate नहीं होतीं।
• Email Validation: email-validator इंस्टॉल होने पर EmailField अब server पर validate करता है।
• CSRF Protection: CSRF protection built-in और cookie-based है। यदि आपने पहले admin को custom CSRF middleware से wrap किया था, तो उसे safely remove कर सकते हैं। Tokens server restarts survive करें, इसके लिए secret_key सेट होना सुनिश्चित करें।
• FileField Upload Size: FileField.max_size अब unlimited के बजाय 50 MB default. पुराना unbounded behavior restore करने के लिए max_size=None pass करें, या cap बदलने के लिए explicit value सेट करें।

Removed with no replacement

• AdminConfig (Authentication देखें).
• datatables_options, responsive_table, और save_state (DataTables Removal देखें).
• Odmantic backend (Requirements देखें).

Getting help

यदि आपको ऐसा migration issue मिले जो इस guide में covered नहीं, तो issue खोलें। Problem का minimal reproduction include करें और बताएँ कि आप किस version से upgrade कर रहे हैं। Admin(debug=True) के साथ चलाने पर cause अक्सर सीधे दिख जाता है, और resulting logs report के लिए बढ़िया addition बनते हैं।