Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #15308 -- Sphinx/reST fixes for the Custom Model Fields docs.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15547 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit a40685fdfcdb1a4fb8769a2d68fbbae632a8cdcd 1 parent 9323f81
authored February 16, 2011

Showing 1 changed file with 57 additions and 54 deletions. Show diff stats Hide diff stats

  1. 111  docs/howto/custom-model-fields.txt
111  docs/howto/custom-model-fields.txt
@@ -105,6 +105,8 @@ say, all the *north* cards first, then the *east*, *south* and *west* cards. So
105 105
 What does a field class do?
106 106
 ---------------------------
107 107
 
  108
+.. class:: Field
  109
+
108 110
 All of Django's fields (and when we say *fields* in this document, we always
109 111
 mean model fields and not :doc:`form fields </ref/forms/fields>`) are subclasses
110 112
 of :class:`django.db.models.Field`. Most of the information that Django records
@@ -190,6 +192,8 @@ card values plus their suits; 104 characters in total.
190 192
     you want your fields to be more strict about the options they select, or
191 193
     to use the simpler, more permissive behavior of the current fields.
192 194
 
  195
+.. method:: Field.__init__
  196
+
193 197
 The :meth:`~django.db.models.Field.__init__` method takes the following
194 198
 parameters:
195 199
 
@@ -228,6 +232,8 @@ meaning they do for normal Django fields. See the :doc:`field documentation
228 232
 The ``SubfieldBase`` metaclass
229 233
 ------------------------------
230 234
 
  235
+.. class:: django.db.models.SubfieldBase
  236
+
231 237
 As we indicated in the introduction_, field subclasses are often needed for
232 238
 two reasons: either to take advantage of a custom database column type, or to
233 239
 handle complex Python types. Obviously, a combination of the two is also
@@ -242,8 +248,6 @@ appropriate Python object. The details of how this happens internally are a
242 248
 little complex, but the code you need to write in your ``Field`` class is
243 249
 simple: make sure your field subclass uses a special metaclass:
244 250
 
245  
-.. class:: django.db.models.SubfieldBase
246  
-
247 251
 For example::
248 252
 
249 253
     class HandField(models.Field):
@@ -255,13 +259,13 @@ For example::
255 259
         def __init__(self, *args, **kwargs):
256 260
             # ...
257 261
 
258  
-This ensures that the :meth:`to_python` method, documented below, will always be
259  
-called when the attribute is initialized.
  262
+This ensures that the :meth:`.to_python` method, documented below, will always
  263
+be called when the attribute is initialized.
260 264
 
261 265
 ModelForms and custom fields
262 266
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
263 267
 
264  
-If you use :class:`~django.db.models.SubfieldBase`, :meth:`to_python`
  268
+If you use :class:`~django.db.models.SubfieldBase`, :meth:`.to_python`
265 269
 will be called every time an instance of the field is assigned a
266 270
 value. This means that whenever a value may be assigned to the field,
267 271
 you need to ensure that it will be of the correct datatype, or that
@@ -277,16 +281,14 @@ Therefore, you must ensure that the form field used to represent your
277 281
 custom field performs whatever input validation and data cleaning is
278 282
 necessary to convert user-provided form input into a
279 283
 `to_python()`-compatible model field value. This may require writing a
280  
-custom form field, and/or implementing the :meth:`formfield` method on
  284
+custom form field, and/or implementing the :meth:`.formfield` method on
281 285
 your field to return a form field class whose `to_python()` returns the
282 286
 correct datatype.
283 287
 
284 288
 Documenting your custom field
285 289
 -----------------------------
286 290
 
287  
-.. class:: django.db.models.Field
288  
-
289  
-.. attribute:: description
  291
+.. attribute:: Field.description
290 292
 
291 293
 As always, you should document your field type, so users will know what it is.
292 294
 In addition to providing a docstring for it, which is useful for developers,
@@ -294,7 +296,7 @@ you can also allow users of the admin app to see a short description of the
294 296
 field type via the :doc:`django.contrib.admindocs
295 297
 </ref/contrib/admin/admindocs>` application. To do this simply provide
296 298
 descriptive text in a ``description`` class attribute of your custom field. In
297  
-the above example, the type description displayed by the ``admindocs``
  299
+the above example, the description displayed by the ``admindocs``
298 300
 application for a ``HandField`` will be 'A hand of cards (bridge style)'.
299 301
 
300 302
 Useful methods
@@ -308,7 +310,7 @@ approximately decreasing order of importance, so start from the top.
308 310
 Custom database types
309 311
 ~~~~~~~~~~~~~~~~~~~~~
310 312
 
311  
-.. method:: db_type(self, connection)
  313
+.. method:: Field.db_type(self, connection)
312 314
 
313 315
 .. versionadded:: 1.2
314 316
    The ``connection`` argument was added to support multiple databases.
@@ -317,8 +319,8 @@ Returns the database column data type for the :class:`~django.db.models.Field`,
317 319
 taking into account the connection object, and the settings associated with it.
318 320
 
319 321
 Say you've created a PostgreSQL custom type called ``mytype``. You can use this
320  
-field with Django by subclassing ``Field`` and implementing the :meth:`db_type`
321  
-method, like so::
  322
+field with Django by subclassing ``Field`` and implementing the
  323
+:meth:`.db_type` method, like so::
322 324
 
323 325
     from django.db import models
324 326
 
@@ -337,8 +339,8 @@ Once you have ``MytypeField``, you can use it in any model, just like any other
337 339
 If you aim to build a database-agnostic application, you should account for
338 340
 differences in database column types. For example, the date/time column type
339 341
 in PostgreSQL is called ``timestamp``, while the same column in MySQL is called
340  
-``datetime``. The simplest way to handle this in a ``db_type()`` method is to
341  
-check the ``connection.settings_dict['ENGINE']`` attribute.
  342
+``datetime``. The simplest way to handle this in a :meth:`.db_type`
  343
+method is to check the ``connection.settings_dict['ENGINE']`` attribute.
342 344
 
343 345
 For example::
344 346
 
@@ -349,11 +351,11 @@ For example::
349 351
             else:
350 352
                 return 'timestamp'
351 353
 
352  
-The :meth:`db_type` method is only called by Django when the framework
353  
-constructs the ``CREATE TABLE`` statements for your application -- that is, when
354  
-you first create your tables. It's not called at any other time, so it can
355  
-afford to execute slightly complex code, such as the ``connection.settings_dict``
356  
-check in the above example.
  354
+The :meth:`.db_type` method is only called by Django when the framework
  355
+constructs the ``CREATE TABLE`` statements for your application -- that is,
  356
+when you first create your tables. It's not called at any other time, so it can
  357
+afford to execute slightly complex code, such as the
  358
+``connection.settings_dict`` check in the above example.
357 359
 
358 360
 Some database column types accept parameters, such as ``CHAR(25)``, where the
359 361
 parameter ``25`` represents the maximum column length. In cases like these,
@@ -390,15 +392,15 @@ time -- i.e., when the class is instantiated. To do that, just implement
390 392
         my_field = BetterCharField(25)
391 393
 
392 394
 Finally, if your column requires truly complex SQL setup, return ``None`` from
393  
-:meth:`db_type`. This will cause Django's SQL creation code to skip over this
394  
-field. You are then responsible for creating the column in the right table in
395  
-some other way, of course, but this gives you a way to tell Django to get out of
396  
-the way.
  395
+:meth:`.db_type`. This will cause Django's SQL creation code to skip
  396
+over this field. You are then responsible for creating the column in the right
  397
+table in some other way, of course, but this gives you a way to tell Django to
  398
+get out of the way.
397 399
 
398 400
 Converting database values to Python objects
399 401
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
400 402
 
401  
-.. method:: to_python(self, value)
  403
+.. method:: Field.to_python(self, value)
402 404
 
403 405
 Converts a value as returned by your database (or a serializer) to a Python
404 406
 object.
@@ -420,7 +422,7 @@ with any of the following arguments:
420 422
 
421 423
 In our ``HandField`` class, we're storing the data as a VARCHAR field in the
422 424
 database, so we need to be able to process strings and ``Hand`` instances in
423  
-:meth:`to_python`::
  425
+:meth:`.to_python`::
424 426
 
425 427
     import re
426 428
 
@@ -442,17 +444,18 @@ Python object type we want to store in the model's attribute.
442 444
 
443 445
 **Remember:** If your custom field needs the :meth:`to_python` method to be
444 446
 called when it is created, you should be using `The SubfieldBase metaclass`_
445  
-mentioned earlier. Otherwise :meth:`to_python` won't be called automatically.
  447
+mentioned earlier. Otherwise :meth:`.to_python` won't be called
  448
+automatically.
446 449
 
447 450
 Converting Python objects to query values
448 451
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
449 452
 
450  
-.. method:: get_prep_value(self, value)
  453
+.. method:: Field.get_prep_value(self, value)
451 454
 
452 455
 .. versionadded:: 1.2
453 456
    This method was factored out of ``get_db_prep_value()``
454 457
 
455  
-This is the reverse of :meth:`to_python` when working with the
  458
+This is the reverse of :meth:`.to_python` when working with the
456 459
 database backends (as opposed to serialization). The ``value``
457 460
 parameter is the current value of the model's attribute (a field has
458 461
 no reference to its containing model, so it cannot retrieve the value
@@ -461,7 +464,7 @@ prepared for use as a parameter in a query.
461 464
 
462 465
 This conversion should *not* include any database-specific
463 466
 conversions. If database-specific conversions are required, they
464  
-should be made in the call to :meth:`get_db_prep_value`.
  467
+should be made in the call to :meth:`.get_db_prep_value`.
465 468
 
466 469
 For example::
467 470
 
@@ -475,43 +478,43 @@ For example::
475 478
 Converting query values to database values
476 479
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
477 480
 
478  
-.. method:: get_db_prep_value(self, value, connection, prepared=False)
  481
+.. method:: Field.get_db_prep_value(self, value, connection, prepared=False)
479 482
 
480 483
 .. versionadded:: 1.2
481 484
    The ``connection`` and ``prepared`` arguments were added to support multiple databases.
482 485
 
483 486
 Some data types (for example, dates) need to be in a specific format
484 487
 before they can be used by a database backend.
485  
-:meth:`get_db_prep_value` is the method where those conversions should
  488
+:meth:`.get_db_prep_value` is the method where those conversions should
486 489
 be made. The specific connection that will be used for the query is
487 490
 passed as the ``connection`` parameter. This allows you to use
488 491
 backend-specific conversion logic if it is required.
489 492
 
490 493
 The ``prepared`` argument describes whether or not the value has
491  
-already been passed through :meth:`get_prep_value` conversions. When
  494
+already been passed through :meth:`.get_prep_value` conversions. When
492 495
 ``prepared`` is False, the default implementation of
493  
-:meth:`get_db_prep_value` will call :meth:`get_prep_value` to do
  496
+:meth:`.get_db_prep_value` will call :meth:`.get_prep_value` to do
494 497
 initial data conversions before performing any database-specific
495 498
 processing.
496 499
 
497  
-.. method:: get_db_prep_save(self, value, connection)
  500
+.. method:: Field.get_db_prep_save(self, value, connection)
498 501
 
499 502
 .. versionadded:: 1.2
500 503
    The ``connection`` argument was added to support multiple databases.
501 504
 
502 505
 Same as the above, but called when the Field value must be *saved* to
503 506
 the database. As the default implementation just calls
504  
-``get_db_prep_value``, you shouldn't need to implement this method
  507
+:meth:`.get_db_prep_value`, you shouldn't need to implement this method
505 508
 unless your custom field needs a special conversion when being saved
506 509
 that is not the same as the conversion used for normal query
507  
-parameters (which is implemented by ``get_db_prep_value``).
  510
+parameters (which is implemented by :meth:`.get_db_prep_value`).
508 511
 
509 512
 Preprocessing values before saving
510 513
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
511 514
 
512  
-.. method:: pre_save(self, model_instance, add)
  515
+.. method:: Field.pre_save(self, model_instance, add)
513 516
 
514  
-This method is called just prior to :meth:`get_db_prep_save` and should return
  517
+This method is called just prior to :meth:`.get_db_prep_save` and should return
515 518
 the value of the appropriate attribute from ``model_instance`` for this field.
516 519
 The attribute name is in ``self.attname`` (this is set up by
517 520
 :class:`~django.db.models.Field`). If the model is being saved to the database
@@ -535,12 +538,12 @@ Preparing values for use in database lookups
535 538
 As with value conversions, preparing a value for database lookups is a
536 539
 two phase process.
537 540
 
538  
-.. method:: get_prep_lookup(self, lookup_type, value)
  541
+.. method:: Field.get_prep_lookup(self, lookup_type, value)
539 542
 
540 543
 .. versionadded:: 1.2
541 544
    This method was factored out of ``get_db_prep_lookup()``
542 545
 
543  
-:meth:`get_prep_lookup` performs the first phase of lookup preparation,
  546
+:meth:`.get_prep_lookup` performs the first phase of lookup preparation,
544 547
 performing generic data validity checks
545 548
 
546 549
 Prepares the ``value`` for passing to the database when used in a lookup (a
@@ -555,7 +558,7 @@ should raise either a ``ValueError`` if the ``value`` is of the wrong sort (a
555 558
 list when you were expecting an object, for example) or a ``TypeError`` if
556 559
 your field does not support that type of lookup. For many fields, you can get
557 560
 by with handling the lookup types that need special handling for your field
558  
-and pass the rest to the :meth:`get_db_prep_lookup` method of the parent class.
  561
+and pass the rest to the :meth:`.get_db_prep_lookup` method of the parent class.
559 562
 
560 563
 If you needed to implement ``get_db_prep_save()``, you will usually need to
561 564
 implement ``get_prep_lookup()``. If you don't, ``get_prep_value`` will be
@@ -586,21 +589,21 @@ accepted lookup types to ``exact`` and ``in``::
586 589
             else:
587 590
                 raise TypeError('Lookup type %r not supported.' % lookup_type)
588 591
 
589  
-.. method:: get_db_prep_lookup(self, lookup_type, value, connection, prepared=False)
  592
+.. method:: Field.get_db_prep_lookup(self, lookup_type, value, connection, prepared=False)
590 593
 
591 594
 .. versionadded:: 1.2
592 595
    The ``connection`` and ``prepared`` arguments were added to support multiple databases.
593 596
 
594 597
 Performs any database-specific data conversions required by a lookup.
595  
-As with :meth:`get_db_prep_value`, the specific connection that will
  598
+As with :meth:`.get_db_prep_value`, the specific connection that will
596 599
 be used for the query is passed as the ``connection`` parameter.
597 600
 The ``prepared`` argument describes whether the value has already been
598  
-prepared with :meth:`get_prep_lookup`.
  601
+prepared with :meth:`.get_prep_lookup`.
599 602
 
600 603
 Specifying the form field for a model field
601 604
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
602 605
 
603  
-.. method:: formfield(self, form_class=forms.CharField, **kwargs)
  606
+.. method:: Field.formfield(self, form_class=forms.CharField, **kwargs)
604 607
 
605 608
 Returns the default form field to use when this field is displayed in a model.
606 609
 This method is called by the :class:`~django.forms.ModelForm` helper.
@@ -613,7 +616,7 @@ field (and even a form widget). See the :doc:`forms documentation
613 616
 </topics/forms/index>` for information about this, and take a look at the code in
614 617
 :mod:`django.contrib.localflavor` for some examples of custom widgets.
615 618
 
616  
-Continuing our ongoing example, we can write the :meth:`formfield` method as::
  619
+Continuing our ongoing example, we can write the :meth:`.formfield` method as::
617 620
 
618 621
     class HandField(models.Field):
619 622
         # ...
@@ -635,14 +638,14 @@ fields.
635 638
 Emulating built-in field types
636 639
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
637 640
 
638  
-.. method:: get_internal_type(self)
  641
+.. method:: Field.get_internal_type(self)
639 642
 
640 643
 Returns a string giving the name of the :class:`~django.db.models.Field`
641 644
 subclass we are emulating at the database level. This is used to determine the
642 645
 type of database column for simple cases.
643 646
 
644  
-If you have created a :meth:`db_type` method, you don't need to worry about
645  
-:meth:`get_internal_type` -- it won't be used much. Sometimes, though, your
  647
+If you have created a :meth:`.db_type` method, you don't need to worry about
  648
+:meth:`.get_internal_type` -- it won't be used much. Sometimes, though, your
646 649
 database storage is similar in type to some other field, so you can use that
647 650
 other field's logic to create the right column.
648 651
 
@@ -657,11 +660,11 @@ For example::
657 660
 No matter which database backend we are using, this will mean that ``syncdb``
658 661
 and other SQL commands create the right column type for storing a string.
659 662
 
660  
-If :meth:`get_internal_type` returns a string that is not known to Django for
  663
+If :meth:`.get_internal_type` returns a string that is not known to Django for
661 664
 the database backend you are using -- that is, it doesn't appear in
662 665
 ``django.db.backends.<db_name>.creation.DATA_TYPES`` -- the string will still be
663  
-used by the serializer, but the default :meth:`db_type` method will return
664  
-``None``. See the documentation of :meth:`db_type` for reasons why this might be
  666
+used by the serializer, but the default :meth:`.db_type` method will return
  667
+``None``. See the documentation of :meth:`.db_type` for reasons why this might be
665 668
 useful. Putting a descriptive string in as the type of the field for the
666 669
 serializer is a useful idea if you're ever going to be using the serializer
667 670
 output in some other place, outside of Django.
@@ -669,7 +672,7 @@ output in some other place, outside of Django.
669 672
 Converting field data for serialization
670 673
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
671 674
 
672  
-.. method:: value_to_string(self, obj)
  675
+.. method:: Field.value_to_string(self, obj)
673 676
 
674 677
 This method is used by the serializers to convert the field into a string for
675 678
 output. Calling :meth:`Field._get_val_from_obj(obj)` is the best way to get the

0 notes on commit a40685f

Please sign in to comment.
Something went wrong with that request. Please try again.