python-docs-ko/library/email.policy.po at 3.6 · python/python-docs-ko

754 lines (652 loc) · 28.2 KB
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001-2017, Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2017.
"Project-Id-Version: Python 3.6\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2017-11-26 18:49+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.5.1\n"
#: ../Doc/library/email.policy.rst:2
msgid ":mod:`email.policy`: Policy Objects"
#: ../Doc/library/email.policy.rst:12
msgid "**Source code:** :source:`Lib/email/policy.py`"
#: ../Doc/library/email.policy.rst:16
"The :mod:`email` package's prime focus is the handling of email messages "
"as described by the various email and MIME RFCs.  However, the general "
"format of email messages (a block of header fields each consisting of a "
"name followed by a colon followed by a value, the whole block followed by"
" a blank line and an arbitrary 'body'), is a format that has found "
"utility outside of the realm of email.  Some of these uses conform fairly"
" closely to the main email RFCs, some do not.  Even when working with "
"email, there are times when it is desirable to break strict compliance "
"with the RFCs, such as generating emails that interoperate with email "
"servers that do not themselves follow the standards, or that implement "
"extensions you want to use in ways that violate the standards."
#: ../Doc/library/email.policy.rst:28
"Policy objects give the email package the flexibility to handle all these"
" disparate use cases."
#: ../Doc/library/email.policy.rst:31
"A :class:`Policy` object encapsulates a set of attributes and methods "
"that control the behavior of various components of the email package "
"during use. :class:`Policy` instances can be passed to various classes "
"and methods in the email package to alter the default behavior.  The "
"settable values and their defaults are described below."
#: ../Doc/library/email.policy.rst:37
"There is a default policy used by all classes in the email package.  For "
"all of the :mod:`~email.parser` classes and the related convenience "
"functions, and for the :class:`~email.message.Message` class, this is the"
" :class:`Compat32` policy, via its corresponding pre-defined instance "
":const:`compat32`.  This policy provides for complete backward "
"compatibility (in some cases, including bug compatibility) with the pre-"
"Python3.3 version of the email package."
#: ../Doc/library/email.policy.rst:44
"This default value for the *policy* keyword to "
":class:`~email.message.EmailMessage` is the :class:`EmailPolicy` policy, "
"via its pre-defined instance :data:`~default`."
#: ../Doc/library/email.policy.rst:48
"When a :class:`~email.message.Message` or "
":class:`~email.message.EmailMessage` object is created, it acquires a "
"policy.  If the message is created by a :mod:`~email.parser`, a policy "
"passed to the parser will be the policy used by the message it creates.  "
"If the message is created by the program, then the policy can be "
"specified when it is created.  When a message is passed to a "
":mod:`~email.generator`, the generator uses the policy from the message "
"by default, but you can also pass a specific policy to the generator that"
" will override the one stored on the message object."
#: ../Doc/library/email.policy.rst:57
"The default value for the *policy* keyword for the :mod:`email.parser` "
"classes and the parser convenience functions **will be changing** in a "
"future version of Python.  Therefore you should **always specify "
"explicitly which policy you want to use** when calling any of the classes"
" and functions described in the :mod:`~email.parser` module."
#: ../Doc/library/email.policy.rst:63
"The first part of this documentation covers the features of "
":class:`Policy`, an :term:`abstract base class` that defines the features"
" that are common to all policy objects, including :const:`compat32`.  "
"This includes certain hook methods that are called internally by the "
"email package, which a custom policy could override to obtain different "
"behavior.  The second part describes the concrete classes "
":class:`EmailPolicy` and :class:`Compat32`, which implement the hooks "
"that provide the standard behavior and the backward compatible behavior "
"and features, respectively."
#: ../Doc/library/email.policy.rst:72
":class:`Policy` instances are immutable, but they can be cloned, "
"accepting the same keyword arguments as the class constructor and "
"returning a new :class:`Policy` instance that is a copy of the original "
"but with the specified attributes values changed."
#: ../Doc/library/email.policy.rst:77
"As an example, the following code could be used to read an email message "
"from a file on disk and pass it to the system ``sendmail`` program on a "
"Unix system:"
#: ../Doc/library/email.policy.rst:113
"Here we are telling :class:`~email.generator.BytesGenerator` to use the "
"RFC correct line separator characters when creating the binary string to "
"feed into ``sendmail's`` ``stdin``, where the default policy would use "
"``\\n`` line separators."
#: ../Doc/library/email.policy.rst:118
"Some email package methods accept a *policy* keyword argument, allowing "
"the policy to be overridden for that method.  For example, the following "
"code uses the :meth:`~email.message.Message.as_bytes` method of the *msg*"
" object from the previous example and writes the message to a file using "
"the native line separators for the platform on which it is running::"
#: ../Doc/library/email.policy.rst:129
"Policy objects can also be combined using the addition operator, "
"producing a policy object whose settings are a combination of the non-"
"default values of the summed objects::"
#: ../Doc/library/email.policy.rst:137
"This operation is not commutative; that is, the order in which the "
"objects are added matters.  To illustrate::"
#: ../Doc/library/email.policy.rst:152
"This is the :term:`abstract base class` for all policy classes.  It "
"provides default implementations for a couple of trivial methods, as well"
" as the implementation of the immutability property, the :meth:`clone` "
"method, and the constructor semantics."
#: ../Doc/library/email.policy.rst:157
"The constructor of a policy class can be passed various keyword "
"arguments. The arguments that may be specified are any non-method "
"properties on this class, plus any additional non-method properties on "
"the concrete class.  A value specified in the constructor will override "
"the default value for the corresponding attribute."
#: ../Doc/library/email.policy.rst:163
"This class defines the following properties, and thus values for the "
"following may be passed in the constructor of any policy class:"
#: ../Doc/library/email.policy.rst:169
"The maximum length of any line in the serialized output, not counting the"
" end of line character(s).  Default is 78, per :rfc:`5322`.  A value of "
"``0`` or :const:`None` indicates that no line wrapping should be done at "
#: ../Doc/library/email.policy.rst:177
"The string to be used to terminate lines in serialized output.  The "
"default is ``\\n`` because that's the internal end-of-line discipline "
"used by Python, though ``\\r\\n`` is required by the RFCs."
#: ../Doc/library/email.policy.rst:184
"Controls the type of Content Transfer Encodings that may be or are "
"required to be used.  The possible values are:"
#: ../Doc/library/email.policy.rst:190
msgid "``7bit``"
#: ../Doc/library/email.policy.rst:190
"all data must be \"7 bit clean\" (ASCII-only).  This means that where "
"necessary data will be encoded using either quoted-printable or base64 "
"encoding."
#: ../Doc/library/email.policy.rst:194
msgid "``8bit``"
#: ../Doc/library/email.policy.rst:194
"data is not constrained to be 7 bit clean.  Data in headers is still "
"required to be ASCII-only and so will be encoded (see :meth:`fold_binary`"
" and :attr:`~EmailPolicy.utf8` below for exceptions), but body parts may "
"use the ``8bit`` CTE."
#: ../Doc/library/email.policy.rst:200
"A ``cte_type`` value of ``8bit`` only works with ``BytesGenerator``, not "
"``Generator``, because strings cannot contain binary data.  If a "
"``Generator`` is operating under a policy that specifies "
"``cte_type=8bit``, it will act as if ``cte_type`` is ``7bit``."
#: ../Doc/library/email.policy.rst:208
"If :const:`True`, any defects encountered will be raised as errors.  If "
":const:`False` (the default), defects will be passed to the "
":meth:`register_defect` method."
#: ../Doc/library/email.policy.rst:215
"If :const:`True`, lines starting with *\"From \"* in the body are escaped"
" by putting a ``>`` in front of them. This parameter is used when the "
"message is being serialized by a generator. Default: :const:`False`."
#: ../Doc/library/email.policy.rst:220
msgid "The *mangle_from_* parameter."
#: ../Doc/library/email.policy.rst:226
"A factory function for constructing a new empty message object.  Used by "
"the parser when building messages.  Defaults to ``None``, in which case "
":class:`~email.message.Message` is used."
#: ../Doc/library/email.policy.rst:232
"The following :class:`Policy` method is intended to be called by code "
"using the email library to create policy instances with custom settings:"
#: ../Doc/library/email.policy.rst:238
"Return a new :class:`Policy` instance whose attributes have the same "
"values as the current instance, except where those attributes are given "
"new values by the keyword arguments."
#: ../Doc/library/email.policy.rst:243
"The remaining :class:`Policy` methods are called by the email package "
"code, and are not intended to be called by an application using the email"
" package. A custom policy must implement all of these methods."
#: ../Doc/library/email.policy.rst:250
"Handle a *defect* found on *obj*.  When the email package calls this "
"method, *defect* will always be a subclass of "
":class:`~email.errors.Defect`."
#: ../Doc/library/email.policy.rst:254
"The default implementation checks the :attr:`raise_on_defect` flag.  If "
"it is ``True``, *defect* is raised as an exception.  If it is ``False`` "
"(the default), *obj* and *defect* are passed to :meth:`register_defect`."
#: ../Doc/library/email.policy.rst:261
"Register a *defect* on *obj*.  In the email package, *defect* will always"
" be a subclass of :class:`~email.errors.Defect`."
#: ../Doc/library/email.policy.rst:264
"The default implementation calls the ``append`` method of the ``defects``"
" attribute of *obj*.  When the email package calls :attr:`handle_defect`,"
" *obj* will normally have a ``defects`` attribute that has an ``append`` "
"method.  Custom object types used with the email package (for example, "
"custom ``Message`` objects) should also provide such an attribute, "
"otherwise defects in parsed messages will raise unexpected errors."
#: ../Doc/library/email.policy.rst:274
msgid "Return the maximum allowed number of headers named *name*."
#: ../Doc/library/email.policy.rst:276
"Called when a header is added to an :class:`~email.message.EmailMessage` "
"or :class:`~email.message.Message` object.  If the returned value is not "
"``0`` or ``None``, and there are already a number of headers with the "
"name *name* greater than or equal to the value returned, a "
":exc:`ValueError` is raised."
#: ../Doc/library/email.policy.rst:282
"Because the default behavior of ``Message.__setitem__`` is to append the "
"value to the list of headers, it is easy to create duplicate headers "
"without realizing it.  This method allows certain headers to be limited "
"in the number of instances of that header that may be added to a "
"``Message`` programmatically.  (The limit is not observed by the parser, "
"which will faithfully produce as many headers as exist in the message "
"being parsed.)"
#: ../Doc/library/email.policy.rst:290
msgid "The default implementation returns ``None`` for all header names."
#: ../Doc/library/email.policy.rst:295
"The email package calls this method with a list of strings, each string "
"ending with the line separation characters found in the source being "
"parsed.  The first line includes the field header name and separator. All"
" whitespace in the source is preserved.  The method should return the "
"``(name, value)`` tuple that is to be stored in the ``Message`` to "
"represent the parsed header."
#: ../Doc/library/email.policy.rst:302
"If an implementation wishes to retain compatibility with the existing "
"email package policies, *name* should be the case preserved name (all "
"characters up to the '``:``' separator), while *value* should be the "
"unfolded value (all line separator characters removed, but whitespace "
"kept intact), stripped of leading whitespace."
#: ../Doc/library/email.policy.rst:308
msgid "*sourcelines* may contain surrogateescaped binary data."
#: ../Doc/library/email.policy.rst:310 ../Doc/library/email.policy.rst:326
#: ../Doc/library/email.policy.rst:342
msgid "There is no default implementation"
#: ../Doc/library/email.policy.rst:315
"The email package calls this method with the name and value provided by "
"the application program when the application program is modifying a "
"``Message`` programmatically (as opposed to a ``Message`` created by a "
"parser).  The method should return the ``(name, value)`` tuple that is to"
" be stored in the ``Message`` to represent the header."
#: ../Doc/library/email.policy.rst:321
"If an implementation wishes to retain compatibility with the existing "
"email package policies, the *name* and *value* should be strings or "
"string subclasses that do not change the content of the passed in "
"arguments."
#: ../Doc/library/email.policy.rst:331
"The email package calls this method with the *name* and *value* currently"
" stored in the ``Message`` when that header is requested by the "
"application program, and whatever the method returns is what is passed "
"back to the application as the value of the header being retrieved. Note "
"that there may be more than one header with the same name stored in the "
"``Message``; the method is passed the specific name and value of the "
"header destined to be returned to the application."
#: ../Doc/library/email.policy.rst:339
"*value* may contain surrogateescaped binary data.  There should be no "
"surrogateescaped binary data in the value returned by the method."
#: ../Doc/library/email.policy.rst:347
"The email package calls this method with the *name* and *value* currently"
" stored in the ``Message`` for a given header.  The method should return "
"a string that represents that header \"folded\" correctly (according to "
"the policy settings) by composing the *name* with the *value* and "
"inserting :attr:`linesep` characters at the appropriate places.  See "
":rfc:`5322` for a discussion of the rules for folding email headers."
#: ../Doc/library/email.policy.rst:354
"*value* may contain surrogateescaped binary data.  There should be no "
"surrogateescaped binary data in the string returned by the method."
#: ../Doc/library/email.policy.rst:360
"The same as :meth:`fold`, except that the returned value should be a "
"bytes object rather than a string."
#: ../Doc/library/email.policy.rst:363
"*value* may contain surrogateescaped binary data.  These could be "
"converted back into binary data in the returned bytes object."
#: ../Doc/library/email.policy.rst:370
"This concrete :class:`Policy` provides behavior that is intended to be "
"fully compliant with the current email RFCs.  These include (but are not "
"limited to) :rfc:`5322`, :rfc:`2047`, and the current MIME RFCs."
#: ../Doc/library/email.policy.rst:374
"This policy adds new header parsing and folding algorithms.  Instead of "
"simple strings, headers are ``str`` subclasses with attributes that "
"depend on the type of the field.  The parsing and folding algorithm fully"
" implement :rfc:`2047` and :rfc:`5322`."
#: ../Doc/library/email.policy.rst:379
"The default value for the :attr:`~email.policy.Policy.message_factory` "
"attribute is :class:`~email.message.EmailMessage`."
#: ../Doc/library/email.policy.rst:382
"In addition to the settable attributes listed above that apply to all "
"policies, this policy adds the following additional attributes:"
#: ../Doc/library/email.policy.rst:385
msgid "[1]_"
#: ../Doc/library/email.policy.rst:390
"If ``False``, follow :rfc:`5322`, supporting non-ASCII characters in "
"headers by encoding them as \"encoded words\".  If ``True``, follow "
":rfc:`6532` and use ``utf-8`` encoding for headers.  Messages formatted "
"in this way may be passed to SMTP servers that support the ``SMTPUTF8`` "
"extension (:rfc:`6531`)."
#: ../Doc/library/email.policy.rst:399
"If the value for a header in the ``Message`` object originated from a "
":mod:`~email.parser` (as opposed to being set by a program), this "
"attribute indicates whether or not a generator should refold that value "
"when transforming the message back into serialized form.  The possible "
"values are:"
#: ../Doc/library/email.policy.rst:406
msgid "``none``"
#: ../Doc/library/email.policy.rst:406
msgid "all source values use original folding"
#: ../Doc/library/email.policy.rst:408
msgid "``long``"
#: ../Doc/library/email.policy.rst:408
"source values that have any line that is longer than ``max_line_length`` "
"will be refolded"
#: ../Doc/library/email.policy.rst:411
msgid "``all``"
#: ../Doc/library/email.policy.rst:411
msgid "all values are refolded."
#: ../Doc/library/email.policy.rst:414
msgid "The default is ``long``."
#: ../Doc/library/email.policy.rst:419
"A callable that takes two arguments, ``name`` and ``value``, where "
"``name`` is a header field name and ``value`` is an unfolded header field"
" value, and returns a string subclass that represents that header.  A "
"default ``header_factory`` (see :mod:`~email.headerregistry`) is provided"
" that supports custom parsing for the various address and date "
":RFC:`5322` header field types, and the major MIME header field stypes.  "
"Support for additional custom parsing will be added in the future."
#: ../Doc/library/email.policy.rst:430
"An object with at least two methods: get_content and set_content.  When "
"the :meth:`~email.message.EmailMessage.get_content` or "
":meth:`~email.message.EmailMessage.set_content` method of an "
":class:`~email.message.EmailMessage` object is called, it calls the "
"corresponding method of this object, passing it the message object as its"
" first argument, and any arguments or keywords that were passed to it as "
"additional arguments.  By default ``content_manager`` is set to "
":data:`~email.contentmanager.raw_data_manager`."
#: ../Doc/library/email.policy.rst:442 ../Doc/library/email.policy.rst:600
"The class provides the following concrete implementations of the abstract"
" methods of :class:`Policy`:"
#: ../Doc/library/email.policy.rst:448
"Returns the value of the "
":attr:`~email.headerregistry.BaseHeader.max_count` attribute of the "
"specialized class used to represent the header with the given name."
#: ../Doc/library/email.policy.rst:456 ../Doc/library/email.policy.rst:606
"The name is parsed as everything up to the '``:``' and returned "
"unmodified.  The value is determined by stripping leading whitespace off "
"the remainder of the first line, joining all subsequent lines together, "
"and stripping any trailing carriage return or linefeed characters."
#: ../Doc/library/email.policy.rst:464
"The name is returned unchanged.  If the input value has a ``name`` "
"attribute and it matches *name* ignoring case, the value is returned "
"unchanged.  Otherwise the *name* and *value* are passed to "
"``header_factory``, and the resulting header object is returned as the "
"value.  In this case a ``ValueError`` is raised if the input value "
"contains CR or LF characters."
#: ../Doc/library/email.policy.rst:474
"If the value has a ``name`` attribute, it is returned to unmodified. "
"Otherwise the *name*, and the *value* with any CR or LF characters "
"removed, are passed to the ``header_factory``, and the resulting header "
"object is returned.  Any surrogateescaped bytes get turned into the "
"unicode unknown-character glyph."
#: ../Doc/library/email.policy.rst:483
"Header folding is controlled by the :attr:`refold_source` policy setting."
" A value is considered to be a 'source value' if and only if it does not "
"have a ``name`` attribute (having a ``name`` attribute means it is a "
"header object of some sort).  If a source value needs to be refolded "
"according to the policy, it is converted into a header object by passing "
"the *name* and the *value* with any CR and LF characters removed to the "
"``header_factory``.  Folding of a header object is done by calling its "
"``fold`` method with the current policy."
#: ../Doc/library/email.policy.rst:492
"Source values are split into lines using :meth:`~str.splitlines`.  If the"
" value is not to be refolded, the lines are rejoined using the "
"``linesep`` from the policy and returned.  The exception is lines "
"containing non-ascii binary data.  In that case the value is refolded "
"regardless of the ``refold_source`` setting, which causes the binary data"
" to be CTE encoded using the ``unknown-8bit`` charset."
#: ../Doc/library/email.policy.rst:502
"The same as :meth:`fold` if :attr:`~Policy.cte_type` is ``7bit``, except "
"that the returned value is bytes."
#: ../Doc/library/email.policy.rst:505
"If :attr:`~Policy.cte_type` is ``8bit``, non-ASCII binary data is "
"converted back into bytes.  Headers with binary data are not refolded, "
"regardless of the ``refold_header`` setting, since there is no way to "
"know whether the binary data consists of single byte characters or "
"multibyte characters."
#: ../Doc/library/email.policy.rst:512
"The following instances of :class:`EmailPolicy` provide defaults suitable"
" for specific application domains.  Note that in the future the behavior "
"of these instances (in particular the ``HTTP`` instance) may be adjusted "
"to conform even more closely to the RFCs relevant to their domains."
#: ../Doc/library/email.policy.rst:520
"An instance of ``EmailPolicy`` with all defaults unchanged.  This policy "
"uses the standard Python ``\\n`` line endings rather than the RFC-correct"
" ``\\r\\n``."
#: ../Doc/library/email.policy.rst:527
"Suitable for serializing messages in conformance with the email RFCs. "
"Like ``default``, but with ``linesep`` set to ``\\r\\n``, which is RFC "
"compliant."
#: ../Doc/library/email.policy.rst:534
"The same as ``SMTP`` except that :attr:`~EmailPolicy.utf8` is ``True``. "
"Useful for serializing messages to a message store without using encoded "
"words in the headers.  Should only be used for SMTP transmission if the "
"sender or recipient addresses have non-ASCII characters (the "
":meth:`smtplib.SMTP.send_message` method handles this automatically)."
#: ../Doc/library/email.policy.rst:543
"Suitable for serializing headers with for use in HTTP traffic.  Like "
"``SMTP`` except that ``max_line_length`` is set to ``None`` (unlimited)."
#: ../Doc/library/email.policy.rst:549
"Convenience instance.  The same as ``default`` except that "
"``raise_on_defect`` is set to ``True``.  This allows any policy to be "
"made strict by writing::"
#: ../Doc/library/email.policy.rst:556
"With all of these :class:`EmailPolicies <.EmailPolicy>`, the effective "
"API of the email package is changed from the Python 3.2 API in the "
"following ways:"
#: ../Doc/library/email.policy.rst:559
"Setting a header on a :class:`~email.message.Message` results in that "
"header being parsed and a header object created."
#: ../Doc/library/email.policy.rst:562
"Fetching a header value from a :class:`~email.message.Message` results in"
" that header being parsed and a header object created and returned."
#: ../Doc/library/email.policy.rst:566
"Any header object, or any header that is refolded due to the policy "
"settings, is folded using an algorithm that fully implements the RFC "
"folding algorithms, including knowing where encoded words are required "
"and allowed."
#: ../Doc/library/email.policy.rst:571
"From the application view, this means that any header obtained through "
"the :class:`~email.message.EmailMessage` is a header object with extra "
"attributes, whose string value is the fully decoded unicode value of the "
"header.  Likewise, a header may be assigned a new value, or a new header "
"created, using a unicode string, and the policy will take care of "
"converting the unicode string into the correct RFC encoded form."
#: ../Doc/library/email.policy.rst:578
"The header objects and their attributes are described in "
":mod:`~email.headerregistry`."
#: ../Doc/library/email.policy.rst:585
"This concrete :class:`Policy` is the backward compatibility policy.  It "
"replicates the behavior of the email package in Python 3.2.  The "
":mod:`~email.policy` module also defines an instance of this class, "
":const:`compat32`, that is used as the default policy.  Thus the default "
"behavior of the email package is to maintain compatibility with Python "
#: ../Doc/library/email.policy.rst:591
"The following attributes have values that are different from the "
":class:`Policy` default:"
#: ../Doc/library/email.policy.rst:597
msgid "The default is ``True``."
#: ../Doc/library/email.policy.rst:614
msgid "The name and value are returned unmodified."
#: ../Doc/library/email.policy.rst:619
"If the value contains binary data, it is converted into a "
":class:`~email.header.Header` object using the ``unknown-8bit`` charset. "
"Otherwise it is returned unmodified."
#: ../Doc/library/email.policy.rst:626
"Headers are folded using the :class:`~email.header.Header` folding "
"algorithm, which preserves existing line breaks in the value, and wraps "
"each resulting line to the ``max_line_length``.  Non-ASCII binary data "
"are CTE encoded using the ``unknown-8bit`` charset."
#: ../Doc/library/email.policy.rst:634
"Headers are folded using the :class:`~email.header.Header` folding "
"algorithm, which preserves existing line breaks in the value, and wraps "
"each resulting line to the ``max_line_length``.  If ``cte_type`` is "
"``7bit``, non-ascii binary data is CTE encoded using the ``unknown-8bit``"
" charset.  Otherwise the original source header is used, with its "
"existing line breaks and any (RFC invalid) binary data it may contain."
#: ../Doc/library/email.policy.rst:644
"An instance of :class:`Compat32`, providing  backward compatibility with "
"the behavior of the email package in Python 3.2."
#: ../Doc/library/email.policy.rst:649
msgid "Footnotes"
#: ../Doc/library/email.policy.rst:650
"Originally added in 3.3 as a :term:`provisional feature <provisional "
"package>`."
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

FilesExpand file tree

email.policy.po

Latest commit

History

email.policy.po

File metadata and controls
