djangodocs

Django 6.1
Gaeilge
Documentation contents

Stíl chódú

Lean na caighdeáin códaithe seo le do thoil agus cód á scríobh agat le cur san áireamh in Django.

Seiceálacha réamhthiomanta

Is creat é `réamh-choimite`_ chun crúca< https://pre-commit.com> í réamhthiomanta a bhainistiú. Cuidíonn na crúcaí seo le saincheisteanna simplí a aithint sula ndéanann siad cód le haghaidh Trí na saincheisteanna seo a sheiceáil roimh athbhreithniú ar chód tugann sé deis don athbhreithneoir díriú ar an athrú féin, agus féadfaidh sé cabhrú freisin le líon na rith CI a laghdú.

Chun an uirlis a úsáid, suiteáil pre-chommit ar dtús agus ansin na crúcaí git:

Linux / macOS

Shell
$ python -m pip install pre-commit
$ pre-commit install

Windows

Windows
...\> py -m pip install pre-commit
...\> pre-commit install

Ar an gcéad tiomantas suiteálfaidh réamh-choimite na crúcaí, suiteáiltear iad seo ina dtimpeallachtaí féin agus tógfaidh siad tamall gairid iad a shuiteáil ar an gcéad rith. Beidh seiceálacha ina dhiaidh sin i bhfad níos tapa Má aimsítear earráid taispeánfar teachtaireacht earráide iomchuí. Má bhí an earráid le dub nó isort ansin rachaidh an uirlis ar aghaidh agus iad a shocrú duit. Déan athbhreithniú ar na hathruithe agus déan athchéim a dhéanamh le tiomantas má tá tú sásta leo.

Stíl Python

  • Ba chóir gach comhad a fhormáidiú ag baint úsáide as an uath-fhormáiditheoir: pypi: black. Reáchtálfaidh réamh-chommit é seo má tá sé sin cumraithe.

  • Cuimsíonn stór an tionscadail comhad .editorconfig. Molaimid eagarthóir téacs a úsáid le tacaíocht EditorConfig chun saincheisteanna insint agus spás bán a sheachaint. Úsáideann na comhaid Python 4 spás le haghaidh ionchur agus úsáideann na comhaid HTML 2 spás.

  • Mura sonraítear a mhalairt, lean: pep: 8.

    Use flake8 to check for problems in this area. Note that our .flake8 file excludes some errors that we don't consider as gross violations. Remember that PEP 8 is only a guide, so respect the style of the surrounding code as a primary goal.

    An exception to PEP 8 is our rules on line lengths. We allow up to 88 characters in code, as this is the line length used by black. Documentation, comments, and docstrings should be wrapped at 79 characters. These limits are checked when flake8 is run.

  • String variable interpolation may use %-formatting, f-strings, or str.format() as appropriate, with the goal of maximizing code readability.

    Fágtar breithiúnais dheiridh ar inléiteacht faoi rogha an Cumaisc. Mar threoir, níor cheart go n-úsáidfeadh f-teaghráin ach rochtain shimplí athróg agus réadmhaoin, le sannadh athróg áitiúil roimhe seo le haghaidh cásanna níos casta:

    Code
    # Allowed
f"hello {user}"
f"hello {user.name}"
f"hello {self.user.name}"

# Disallowed
f"hello {get_user()}"
f"you are {user.age * 365.25} days old"

# Allowed with local variable assignment
user = get_user()
f"hello {user}"
user_days_old = user.age * 365.25
f"you are {user_days_old} days old"

    níor cheart f-teaghráin a úsáid le haghaidh teaghrán ar bith a bhféadfadh aistriúchán a bheith ag teastáil uaidh, lena n-áirítear teachtaireachtaí earráide agus logáil. Go ginearálta bíonn formáid() níos briathartha, mar sin is fearr na modhanna formáidithe eile.

    Ná cuir am amú ag déanamh athfhachtóirí neamhghaolmhara ar an gcód atá ann cheana chun an modh formáidithe a choigeartú.

  • Seachain úsáid “muid” i dtráchtanna, m.sh. “Lúb thar” seachas “Táimid lúb thart”.

  • Úsáid béim, ní CamelCase, le haghaidh ainmneacha athróg, feidhm agus modh (ie poll.get_unique_votes () ``, ní ``poll.getUniqueVoters ()).

  • Úsáid InitialCaps le haghaidh ainmneacha ranga (nó le haghaidh feidhmeanna monarcha a thugann ranganna ar ais).

  • I docstrings, lean stíl na docstrings atá ann cheana agus: pep: 257.

  • I dtástálacha, bain úsáid ai:meth: ~django.test.simpletestcase.assertRaisesMessage agus:meth: ~django.test.simpletestCase.assertWarnsMessage in ionad:meth: ~UnitTest.TestCase.AsserTraises agus:meth: ~UnitTest.TestCase.Asserns ionas gur féidir leat an eisceacht nó teachtaireacht rabhaidh. Úsáid: Meth: ~UnitTest.TestCase.AsserTraisesRegex agus:meth: ~UnitTest.TestCase.AssertWarnsRegex ach amháin má theastaíonn meaitseáil léirithe rialta uait.

    Úsáid: Meth: Assertis (..., True/False) <unittest.TestCase.assertIs>`chun luachanna boolean a thástáil, seachas: meth: `~UnitTest.TestCase.AssertTrue agus:meth: ~UnitTest.TestCase.assertFalse, ionas gur féidir leat an luach boolean iarbhír a sheiceáil, ní fírinneacht an abairt.

  • I ndocstrings tástála, luaigh an t-iompar a bhfuiltear ag súil leis a léiríonn gach tástáil. Ná cuir réamhshamhlacha mar “Tástálacha sin” nó “Cinntíonn sé sin” san áireamh.

    Tagairtí ticéad a chur in áirithe le haghaidh saincheisteanna doiléire ina bhfuil sonraí breise sa ticéad nach féidir cur síos a dhéanamh orthu go héasca i ndocstrings nó i dtuairimí. Cuir uimhir an ticéad san áireamh ag deireadh abairt mar seo:

    Code
    def test_foo():
    """
    A test docstring looks like this (#123456).
    """
    ...

  • Where applicable, use unpacking generalizations compliant with PEP 448, such as merging mappings ({**x, **y}) or sequences ([*a, *b]). This improves performance, readability, and maintainability while reducing errors.

Allmhairí

  • Úsáid isort chun sórtáil iompórtála a uathoibriú ag baint úsáide as na treoirlínte thíos.

    Tús tapa:

    Linux / macOS

    Shell
    $ python -m pip install "isort >= 7.0.0"
$ isort .

    Windows

    Windows
    ...\> py -m pip install "isort >= 7.0.0"
...\> isort .

    Ritheann sé seo isort go athshlánach ó d'eolaire reatha, ag modhnú aon chomhaid nach gcomhlíonann leis na treoirlínte. Más gá duit allmhairí a bheith as ord (chun allmhairiú ciorclach a sheachaint, mar shampla) bain úsáid as trácht mar seo:

    Code
    import module  # isort:skip

  • Put imports in these groups: future, standard library, third-party libraries, other Django components, local Django component, try/excepts. Sort lines in each group alphabetically by the full module name. Place all import module statements before from module import objects in each section. Use absolute imports for other Django components and a one-dot relative import (from .foo import Bar) for local components. Avoid multi-dot relative imports.

  • Ar gach líne, déan na míreanna aibítir leis na míreanna uachtarcháis atá grúpáilte roimh na míreanna beaga.

  • Briseadh línte fada ag baint úsáide as lúibíní agus línte leanúna le 4 spás. Cuir camóg siar san áireamh tar éis an allmhairiú deireanach agus cuir an lúibín deiridh ar a líne féin.

    Úsáid líne bán amháin idir an t-allmhairiú deireanach agus aon chód leibhéal an mhodúil, agus bain úsáid as dhá líne bán os cionn an chéad fheidhm nó an rang.

    Mar shampla (tá tuairimí chun críocha míniúcháin amháin):

    django/contrib/admin/example.py
    Python
    # future
from __future__ import annotations

# standard library
import json
from itertools import chain

# third-party
import bcrypt

# Django
from django.http import Http404
from django.http.response import (
    Http404,
    HttpResponse,
    HttpResponseNotAllowed,
    StreamingHttpResponse,
    cookie,
)

# local Django
from .models import LogEntry

# try/except
try:
    import yaml
except ImportError:
    yaml = None

CONSTANT = "foo"


class Example: ...

  • Úsáid allmhairí áisiúlachta aon uair atá Mar shampla, déan seo:

    Code
    from django.views import View

    in ionad:

    Code
    from django.views.generic.base import View

Stíl teimpléad

Lean na rialacha thíos i gcód teimpléad Django.

  • Ba chóir gurb é {% leathnaíonn%} an chéad líne neamh-trácht.

    Déan é seo:

    Django template
    {% extends "base.html" %}

{% block content %}
  <h1 class="font-semibold text-xl">
    {{ pages.title }}
  </h1>
{% endblock content %}

    Nó seo:

    Django template
    {# This is a comment #}
{% extends "base.html" %}

{% block content %}
  <h1 class="font-semibold text-xl">
    {{ pages.title }}
  </h1>
{% endblock content %}

    Ná déan é seo:

    Django template
    {% load i18n %}
{% extends "base.html" %}

{% block content %}
  <h1 class="font-semibold text-xl">
    {{ pages.title }}
  </h1>
{% endblock content %}

  • Cuir spás amháin go díreach idir {{, ábhar athraitheach, agus }}.

    Déan é seo:

    Django template
    {{ user }}

    Ná déan é seo:

    Django template
    {{user}}

  • I ``{% load...%} `, liostaigh leabharlanna in ord aibítre.

    Déan é seo:

    Django template
    {% load i18n l10 tz %}

    Ná déan é seo:

    Django template
    {% load l10 i18n tz %}

  • Cuir spás amháin go díreach idir {%, ábhar clibeanna, agus %}.

    Déan é seo:

    Django template
    {% load humanize %}

    Ná déan é seo:

    Django template
    {%load humanize%}

  • Cuir ainm an chlib {% block%} sa chlib {% endblock%} mura bhfuil sé ar an líne chéanna.

    Déan é seo:

    Django template
    {% block header %}

  Code goes here

{% endblock header %}

    Ná déan é seo:

    Django template
    {% block header %}

  Code goes here

{% endblock %}

  • Taobh istigh de bhraiceanna cuartha, comharthaí ar leithligh de réir spásanna aonair, ach amháin timpeall an . le haghaidh rochtana tréithe agus an | le haghaidh scagaire.

    Déan é seo:

    Django template
    {% if user.name|lower == "admin" %}

    Ná déan é seo:

    Django template
    {% if user . name | lower  ==  "admin" %}

{{ user.name | upper }}

  • Laistigh de theimpléad ag baint úsáide as {% leathnaíonn%}, seachain clibeanna ``{% block%} `a chur isteach.

    Déan é seo:

    Django template
    {% extends "base.html" %}

{% block content %}

    Ná déan é seo:

    Django template
    {% extends "base.html" %}

  {% block content %}
  ...

Féach ar stíl

  • I dtuairimí Django, ba chóir “iarratas” a thabhairt ar an gcéad pharaiméadar i bhfeidhm amharc.

    Déan seo:

    Code
    def my_view(request, foo): ...

    Ná déan seo:

    Code
    def my_view(req, foo): ...

Stíl mhúnla

  • Ba chóir go mbeadh ainmneacha réimse le litreacha beaga uile, ag úsáid béim in ionad CamelCase.

    Déan seo:

    Code
    class Person(models.Model):
    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=40)

    Ná déan seo:

    Code
    class Person(models.Model):
    FirstName = models.CharField(max_length=20)
    Last_Name = models.CharField(max_length=40)

  • Ba chóir go mbeadh an aicme Meta` le feiceáil* tar éis * na réimsí a shainiú, le líne bán amháin a scarann na réimsí agus an sainmhíniú ranga.

    Déan seo:

    Code
    class Person(models.Model):
    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=40)

    class Meta:
        verbose_name_plural = "people"

    Ná déan seo:

    Code
    class Person(models.Model):
    class Meta:
        verbose_name_plural = "people"

    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=40)

  • Ba chóir go mbeadh ord ranganna istigh samhail agus modhanna caighdeánacha mar seo a leanas (ag tabhairt faoi deara nach bhfuil siad seo uile ag teastáil):

    • Gach réimse bunachar sonraí

    • Tréithe bainisteoir saincheaptha

    • Aicme Meta

    • def __str__() and other Python magic methods

    • ``def sábháil () ``

    • ``def get_absolute_url () ``

    • Aon mhodhanna saincheaptha

  • Má shainmhínítear “roghanna” do réimse samhail ar leith, sainmhínigh gach rogha mar mhapáil, le ainm uile-uachtaracha mar thréith aicme ar an tsamhail. Sampla:

    Code
    class MyModel(models.Model):
    DIRECTION_UP = "U"
    DIRECTION_DOWN = "D"
    DIRECTION_CHOICES = {
        DIRECTION_UP: "Up",
        DIRECTION_DOWN: "Down",
    }

    De rogha air sin, smaoinigh ar úsáid:ref: field-choices-enum-typepes:

    Code
    class MyModel(models.Model):
    class Direction(models.TextChoices):
        UP = "U", "Up"
        DOWN = "D", "Down"

Úsáid django.conf.settings

Níor chóir modúil úsáid go ginearálta socruithe a stóráiltear i django.conf.settings` ag an leibhéal barr (ie meastóireacht nuair a dhéantar an modúl a allmhairiú). Is é seo a leanas an míniú ar seo:

Ceadaítear cumraíocht láimhe na socruithe (ie gan brath ar an athróg comhshaoil: envvar: DJANGO_SETTINGS_MODULE) agus is féidir mar seo a leanas:

Code
from django.conf import settings

settings.configure({}, SOME_SETTING="foo")

Mar sin féin, má dhéantar rochtain ar aon socrú roimh an líne settings.configure, ní oibreoidh sé seo. (Go hinmheánach, is lazyObject é `socruithe ``a chumraíonn é féin go huathoibríoch nuair a bhíonn rochtain ar na socruithe mura bhfuil sé cumraithe cheana féin).

Mar sin, má tá modúl ann ina bhfuil cód éigin mar seo a leanas:

Code
from django.conf import settings
from django.urls import get_callable

default_foo_view = get_callable(settings.FOO_VIEW)

... ansin beidh an modúl seo a allmhairiú mar thoradh ar an réad socruithe a chumrú. Ciallaíonn sé sin go bhfuil an cumas do thríú páirtithe an modúl a iompórtáil ag an leibhéal barr comhoiriúnach leis an gcumas an réad socruithe a chumrú de láimh, nó go ndéanann sé an-deacair i gcúinsí áirithe.

In ionad an chód thuas, caithfear leibhéal leisce nó intreo a úsáid, mar shampla django.utils.functional.lazyobject, django.utils.functional.lazy () ``nó ``lambda`.

Ilghnéitheach

  • Marcáil na teaghráin go léir le haghaidh idirnáisiúnaithe; féach an doiciméadú: doc: i</topics/i18n/index> 18n le haghaidh sonraí.

  • Bain ráitis `allmhairi nach n-úsáidtear a thuilleadh nuair a athraíonn tú cód. :pypi: aithneoidh flake8 na hallmhairí seo duit. Más gá allmhairiú neamhúsáidte fanacht le haghaidh comhoiriúnacht ar ais, marcáil deireadh le # NOQA` chun an rabhadh flake8 a thostú.

  • Bain gach spás bán rianúil ó do chód go córasach de réir mar a chuireann siad sin béite neamhriachtanacha leis, cuireann siad neamhghnách amhairc leis na paistí agus is féidir leo coimhlintí cumaisc gan ghá a chur faoi Is féidir roinnt IDE a chumrú chun iad a bhaint go huathoibríoch agus is féidir an chuid is mó d'uirlisí VCS a shocrú chun aird a tharraingt orthu in aschuir diff.

  • Ná cuir d'ainm sa chód a chuireann tú le do thoil. Is é ár mbeartas ainmneacha rannpháirtithe a choinneáil sa chomhad ``AUTHORS` a dháiltear le Django - gan scaipthe ar fud an chód-bhunachar féin. Ná bíodh leisce ort athrú ar an gcomhad ``AUTHORS` a chur san áireamh i do phaiste má dhéanann tú níos mó ná athrú tábhachtach amháin.

Stíl JavaScript

For details about the JavaScript code style used by Django, see Cód JavaScript.

View as Markdown Edit this page on GitHub Official version