~ubuntu-branches/debian/sid/python-django/sid

.. method:: add_item(title, link, description, [author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, enclosure=None, categories=(), item_copyright=None, ttl=None, **kwargs])

341

371

342

372

343

Adds an item to the feed. All args are expected to be Python ``unicode``

373

objects except ``pubdate``, which is a ``datetime.datetime`` object, and

374

``enclosure``, which is an instance of the ``Enclosure`` class.

344

objects except ``pubdate`` and ``updateddate``, which are ``datetime.datetime``

345

objects, and ``enclosure``, which is an instance of the ``Enclosure`` class.

346

347

.. versionadded:: 1.7

348

349

The optional ``updateddate`` argument was added.

375

350

376

351

.. method:: num_items()

377

352

405

380

406

381

.. method:: latest_post_date()

407

382

408

Returns the latest item's ``pubdate``. If none of them have a

409

``pubdate``, this returns the current date/time.

383

Returns the latest ``pubdate`` or ``updateddate`` for all items in the

384

feed. If no items have either of these attributes this returns the

385

current date/time.

410

386

411

387

Enclosure

412

388

---------

456

432

457

433

Consider a typical case, where a view might need to call a model's method

458

434

to perform some computation, before placing the model instance into the

459

context, where the template might invoke the method once more::

435

context, where the template might invoke the method once more:

436

437

.. code-block:: python

460

438

461

439

# the model

462

440

class Person(models.Model):

507

485

508

486

.. function:: allow_lazy(func, *resultclasses)

509

487

510

Django offers many utility functions (particularly in ``django.utils``) that

511

take a string as their first argument and do something to that string. These

512

functions are used by template filters as well as directly in other code.

488

Django offers many utility functions (particularly in ``django.utils``)

489

that take a string as their first argument and do something to that string.

490

These functions are used by template filters as well as directly in other

491

code.

513

492

514

493

If you write your own similar functions and deal with translations, you'll

515

face the problem of what to do when the first argument is a lazy translation

516

object. You don't want to convert it to a string immediately, because you might

517

be using this function outside of a view (and hence the current thread's locale

518

setting will not be correct).

494

face the problem of what to do when the first argument is a lazy

495

translation object. You don't want to convert it to a string immediately,

496

because you might be using this function outside of a view (and hence the

497

current thread's locale setting will not be correct).

519

498

520

499

For cases like this, use the ``django.utils.functional.allow_lazy()``

521

500

decorator. It modifies the function so that *if* it's called with a lazy

522

translation as the first argument, the function evaluation is delayed until it

523

needs to be converted to a string.

501

translation as one of its arguments, the function evaluation is delayed

502

until it needs to be converted to a string.

524

503

525

504

For example::

526

505

532

511

# Replace unicode by str on Python 3

533

512

fancy_utility_function = allow_lazy(fancy_utility_function, unicode)

534

513

535

The ``allow_lazy()`` decorator takes, in addition to the function to decorate,

536

a number of extra arguments (``*args``) specifying the type(s) that the

537

original function can return. Usually, it's enough to include ``unicode``

538

(or ``str`` on Python 3) here and ensure that your function returns only

539

Unicode strings.

514

The ``allow_lazy()`` decorator takes, in addition to the function to

515

decorate, a number of extra arguments (``*args``) specifying the type(s)

516

that the original function can return. Usually, it's enough to include

517

``unicode`` (or ``str`` on Python 3) here and ensure that your function

518

returns only Unicode strings.

540

519

541

520

Using this decorator means you can write your function and assume that the

542

input is a proper string, then add support for lazy translation objects at the

543

end.

521

input is a proper string, then add support for lazy translation objects at

522

the end.

544

523

545

524

``django.utils.html``

546

525

=====================

562

541

563

542

.. function:: conditional_escape(text)

564

543

565

Similar to ``escape()``, except that it doesn't operate on pre-escaped strings,

566

so it will not double escape.

544

Similar to ``escape()``, except that it doesn't operate on pre-escaped

545

strings, so it will not double escape.

567

546

568

547

.. function:: format_html(format_string, *args, **kwargs)

569

548

654

633

655

634

remove_tags(value, "b span")

656

635

657

If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"`` the

658

return value will be ``"Joel <button>is</button> a slug"``.

636

If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"``

637

the return value will be ``"Joel <button>is</button> a slug"``.

659

638

660

639

Note that this filter is case-sensitive.

661

640

662

If ``value`` is ``"<B>Joel</B> <button>is</button> a <span>slug</span>"`` the

663

return value will be ``"<B>Joel</B> <button>is</button> a slug"``.

641

If ``value`` is ``"<B>Joel</B> <button>is</button> a <span>slug</span>"``

642

the return value will be ``"<B>Joel</B> <button>is</button> a slug"``.

664

643

665

644

.. _str.format: http://docs.python.org/library/stdtypes.html#str.format

666

645

721

700

.. function:: int_to_base36(i)

722

701

723

702

Converts a positive integer to a base 36 string. On Python 2 ``i`` must be

724

smaller than :data:`sys.maxint`.

703

smaller than `sys.maxint`_.

704

705

.. _sys.maxint: http://docs.python.org/2/library/sys.html#sys.maxint

725

706

726

707

.. function:: urlsafe_base64_encode(s)

727

708

745

726

746

727

Functions for working with Python modules.

747

728

729

.. function:: import_string(dotted_path)

730

731

.. versionadded:: 1.7

732

733

Imports a dotted module path and returns the attribute/class designated by

734

the last name in the path. Raises ``ImportError`` if the import failed. For

735

example::

736

737

from django.utils.module_loading import import_string

738

ValidationError = import_string('django.core.exceptions.ValidationError')

739

740

is equivalent to::

741

742

from django.core.exceptions import ValidationError

743

748

744

.. function:: import_by_path(dotted_path, error_prefix='')

749

745

750

746

.. versionadded:: 1.6

747

.. deprecated:: 1.7

748

Use :meth:`~django.utils.module_loading.import_string` instead.

751

749

752

750

Imports a dotted module path and returns the attribute/class designated by

753

the last name in the path. Raises

754

:exc:`~django.core.exceptions.ImproperlyConfigured` if something goes

755

wrong. For example::

756

757

from django.utils.module_loading import import_by_path

758

ImproperlyConfigured = import_by_path('django.core.exceptions.ImproperlyConfigured')

759

760

is equivalent to::

761

762

from django.core.exceptions import ImproperlyConfigured

751

the last name in the path. Raises :exc:`~django.core.exceptions.ImproperlyConfigured`

752

if something goes wrong.

763

753

764

754

``django.utils.safestring``

765

755

===========================

775

765

776

766

.. class:: SafeBytes

777

767

778

.. versionadded:: 1.5

779

780

768

A ``bytes`` subclass that has been specifically marked as "safe"

781

769

(requires no further escaping) for HTML output purposes.

782

770

788

776

789

777

.. class:: SafeText

790

778

791

.. versionadded:: 1.5

792

793

779

A ``str`` (in Python 3) or ``unicode`` (in Python 2) subclass

794

780

that has been specifically marked as "safe" for HTML output purposes.

795

781

832

818

.. function:: slugify

833

819

834

820

Converts to lowercase, removes non-word characters (alphanumerics and

835

underscores) and converts spaces to hyphens. Also strips leading and trailing

836

whitespace.

821

underscores) and converts spaces to hyphens. Also strips leading and

822

trailing whitespace.

837

823

838

824

For example::

839

825

840

826

slugify(value)

841

827

842

If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``.

843

844

``django.utils.translation``

845

============================

846

847

.. module:: django.utils.translation

848

:synopsis: Internationalization support.

849

850

For a complete discussion on the usage of the following see the

851

:doc:`translation documentation </topics/i18n/translation>`.

852

853

.. function:: gettext(message)

854

855

Translates ``message`` and returns it in a UTF-8 bytestring

856

857

.. function:: ugettext(message)

858

859

Translates ``message`` and returns it in a unicode string

860

861

.. function:: pgettext(context, message)

862

863

Translates ``message`` given the ``context`` and returns

864

it in a unicode string.

865

866

For more information, see :ref:`contextual-markers`.

867

868

.. function:: gettext_lazy(message)

869

.. function:: ugettext_lazy(message)

870

.. function:: pgettext_lazy(context, message)

871

872

Same as the non-lazy versions above, but using lazy execution.

873

874

See :ref:`lazy translations documentation <lazy-translations>`.

875

876

.. function:: gettext_noop(message)

877

.. function:: ugettext_noop(message)

878

879

Marks strings for translation but doesn't translate them now. This can be

880

used to store strings in global variables that should stay in the base

881

language (because they might be used externally) and will be translated

882

later.

883

884

.. function:: ngettext(singular, plural, number)

885

886

Translates ``singular`` and ``plural`` and returns the appropriate string

887

based on ``number`` in a UTF-8 bytestring.

888

889

.. function:: ungettext(singular, plural, number)

890

891

Translates ``singular`` and ``plural`` and returns the appropriate string

892

based on ``number`` in a unicode string.

893

894

.. function:: npgettext(context, singular, plural, number)

895

896

Translates ``singular`` and ``plural`` and returns the appropriate string

897

based on ``number`` and the ``context`` in a unicode string.

898

899

.. function:: ngettext_lazy(singular, plural, number)

900

.. function:: ungettext_lazy(singular, plural, number)

901

.. function:: npgettext_lazy(context, singular, plural, number)

902

903

Same as the non-lazy versions above, but using lazy execution.

904

905

See :ref:`lazy translations documentation <lazy-translations>`.

906

907

.. function:: string_concat(*strings)

908

909

Lazy variant of string concatenation, needed for translations that are

910

constructed from multiple parts.

911

912

.. function:: activate(language)

913

914

Fetches the translation object for a given language and installs it as

915

the current translation object for the current thread.

916

917

.. function:: deactivate()

918

919

De-installs the currently active translation object so that further _ calls

920

will resolve against the default translation object, again.

921

922

.. function:: deactivate_all()

923

924

Makes the active translation object a NullTranslations() instance. This is

925

useful when we want delayed translations to appear as the original string

926

for some reason.

927

928

.. function:: override(language, deactivate=False)

929

930

A Python context manager that uses

931

:func:`django.utils.translation.activate` to fetch the translation object

932

for a given language, installing it as the translation object for the

933

current thread and reinstall the previous active language on exit.

934

Optionally it can simply deinstall the temporary translation on exit with

935

:func:`django.utils.translation.deactivate` if the deactivate argument is

936

True. If you pass None as the language argument, a NullTranslations()

937

instance is installed while the context is active.

938

939

.. function:: get_language()

940

941

Returns the currently selected language code.

942

943

.. function:: get_language_bidi()

944

945

Returns selected language's BiDi layout:

946

947

* ``False`` = left-to-right layout

948

* ``True`` = right-to-left layout

949

950

.. function:: get_language_from_request(request, check_path=False)

951

952

Analyzes the request to find what language the user wants the system to show.

953

Only languages listed in settings.LANGUAGES are taken into account. If the user

954

requests a sublanguage where we have a main language, we send out the main

955

language.

956

957

If ``check_path`` is ``True``, the function first checks the requested URL

958

for whether its path begins with a language code listed in the

959

:setting:`LANGUAGES` setting.

960

961

.. function:: to_locale(language)

962

963

Turns a language name (en-us) into a locale name (en_US).

964

965

.. function:: templatize(src)

966

967

Turns a Django template into something that is understood by xgettext. It does

968

so by translating the Django translation tags into standard gettext function

969

invocations.

828

If ``value`` is ``"Joel is a slug"``, the output will be

829

``"joel-is-a-slug"``.

970

830

971

831

.. _time-zone-selection-functions:

972

832

980

840

981

841

:class:`~datetime.tzinfo` instance that represents UTC.

982

842

843

.. function:: get_fixed_timezone(offset)

844

845

.. versionadded:: 1.7

846

847

Returns a :class:`~datetime.tzinfo` instance that represents a time zone

848

with a fixed offset from UTC.

849

850

``offset`` is a :class:`datetime.timedelta` or an integer number of

851

minutes. Use positive values for time zones east of UTC and negative

852

values for west of UTC.

853

983

854

.. function:: get_default_timezone()

984

855

985

856

Returns a :class:`~datetime.tzinfo` instance that represents the

1018

889

``None``, the :ref:`current time zone <default-current-time-zone>` is unset

1019

890

on entry with :func:`deactivate()` instead.

1020

891

1021

.. versionadded:: 1.5

1022

1023

892

.. function:: localtime(value, timezone=None)

1024

893

1025

894

Converts an aware :class:`~datetime.datetime` to a different time zone,

1073

942

1074

943

.. _pytz: http://pytz.sourceforge.net/

1075

944

945

``django.utils.translation``

946

============================

947

948

.. module:: django.utils.translation

949

:synopsis: Internationalization support.

950

951

For a complete discussion on the usage of the following see the

952

:doc:`translation documentation </topics/i18n/translation>`.

953

954

.. function:: gettext(message)

955

956

Translates ``message`` and returns it in a UTF-8 bytestring

957

958

.. function:: ugettext(message)

959

960

Translates ``message`` and returns it in a unicode string

961

962

.. function:: pgettext(context, message)

963

964

Translates ``message`` given the ``context`` and returns

965

it in a unicode string.

966

967

For more information, see :ref:`contextual-markers`.

968

969

.. function:: gettext_lazy(message)

970

.. function:: ugettext_lazy(message)

971

.. function:: pgettext_lazy(context, message)

972

973

Same as the non-lazy versions above, but using lazy execution.

974

975

See :ref:`lazy translations documentation <lazy-translations>`.

976

977

.. function:: gettext_noop(message)

978

.. function:: ugettext_noop(message)

979

980

Marks strings for translation but doesn't translate them now. This can be

981

used to store strings in global variables that should stay in the base

982

language (because they might be used externally) and will be translated

983

later.

984

985

.. function:: ngettext(singular, plural, number)

986

987

Translates ``singular`` and ``plural`` and returns the appropriate string

988

based on ``number`` in a UTF-8 bytestring.

989

990

.. function:: ungettext(singular, plural, number)

991

992

Translates ``singular`` and ``plural`` and returns the appropriate string

993

based on ``number`` in a unicode string.

994

995

.. function:: npgettext(context, singular, plural, number)

996

997

Translates ``singular`` and ``plural`` and returns the appropriate string

998

based on ``number`` and the ``context`` in a unicode string.

999

1000

.. function:: ngettext_lazy(singular, plural, number)

1001

.. function:: ungettext_lazy(singular, plural, number)

1002

.. function:: npgettext_lazy(context, singular, plural, number)

1003

1004

Same as the non-lazy versions above, but using lazy execution.

1005

1006

See :ref:`lazy translations documentation <lazy-translations>`.

1007

1008

.. function:: string_concat(*strings)

1009

1010

Lazy variant of string concatenation, needed for translations that are

1011

constructed from multiple parts.

1012

1013

.. function:: activate(language)

1014

1015

Fetches the translation object for a given language and activates it as

1016

the current translation object for the current thread.

1017

1018

.. function:: deactivate()

1019

1020

Deactivates the currently active translation object so that further _ calls

1021

will resolve against the default translation object, again.

1022

1023

.. function:: deactivate_all()

1024

1025

Makes the active translation object a ``NullTranslations()`` instance.

1026

This is useful when we want delayed translations to appear as the original

1027

string for some reason.

1028

1029

.. function:: override(language, deactivate=False)

1030

1031

A Python context manager that uses

1032

:func:`django.utils.translation.activate` to fetch the translation object

1033

for a given language, activates it as the translation object for the

1034

current thread and reactivates the previous active language on exit.

1035

Optionally, it can simply deactivate the temporary translation on exit with

1036

:func:`django.utils.translation.deactivate` if the ``deactivate`` argument

1037

is ``True``. If you pass ``None`` as the language argument, a

1038

``NullTranslations()`` instance is activated within the context.

1039

1040

.. function:: get_language()

1041

1042

Returns the currently selected language code.

1043

1044

.. function:: get_language_bidi()

1045

1046

Returns selected language's BiDi layout:

1047

1048

* ``False`` = left-to-right layout

1049

* ``True`` = right-to-left layout

1050

1051

.. function:: get_language_from_request(request, check_path=False)

1052

1053

Analyzes the request to find what language the user wants the system to

1054

show. Only languages listed in settings.LANGUAGES are taken into account.

1055

If the user requests a sublanguage where we have a main language, we send

1056

out the main language.

1057

1058

If ``check_path`` is ``True``, the function first checks the requested URL

1059

for whether its path begins with a language code listed in the

1060

:setting:`LANGUAGES` setting.

1061

1062

.. function:: to_locale(language)

1063

1064

Turns a language name (en-us) into a locale name (en_US).

1065

1066

.. function:: templatize(src)

1067

1068

Turns a Django template into something that is understood by ``xgettext``.

1069

It does so by translating the Django translation tags into standard

1070

``gettext`` function invocations.

1071

1072

.. data:: LANGUAGE_SESSION_KEY

1073

1074

Session key under which the active language for the current session is

1075

stored.

1076

1077

``django.utils.tzinfo``

1077

1078

=======================

1078

1079

1080

.. deprecated:: 1.7

1081

Use :mod:`~django.utils.timezone` instead.

1082

1079

1083

.. module:: django.utils.tzinfo

1080

1084

:synopsis: Implementation of ``tzinfo`` classes for use with ``datetime.datetime``.

1081

1085

1083

1087

1084

1088

Fixed offset in minutes east from UTC.

1085

1089

1090

.. deprecated:: 1.7

1091

Use :func:`~django.utils.timezone.get_fixed_timezone` instead.

1092

1086

1093

.. class:: LocalTimezone

1087

1094

1088

1095

Proxy timezone information from time module.

1096

1097

.. deprecated:: 1.7

1098

Use :func:`~django.utils.timezone.get_default_timezone` instead.

Older »