python-docs-pl/howto/descriptor.po at 3.10 · python/python-docs-pl

879 lines (704 loc) · 26.8 KB
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001-2026, Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
# Translators:
# python-doc bot, 2025
"Project-Id-Version: Python 3.10\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-04-09 18:19+0000\n"
"PO-Revision-Date: 2025-09-22 15:57+0000\n"
"Last-Translator: python-doc bot, 2025\n"
"Language-Team: Polish (https://app.transifex.com/python-doc/teams/5390/pl/)\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Language: pl\n"
"Plural-Forms: nplurals=4; plural=(n==1 ? 0 : (n%10>=2 && n%10<=4) && "
"(n%100<12 || n%100>14) ? 1 : n!=1 && (n%10>=0 && n%10<=1) || (n%10>=5 && "
"n%10<=9) || (n%100>=12 && n%100<=14) ? 2 : 3);\n"
msgid "Descriptor HowTo Guide"
msgid "Author"
msgstr "Autor"
msgid "Raymond Hettinger"
msgstr "Raymond Hettinger"
msgid "Contact"
msgid "<python at rcn dot com>"
msgid "Contents"
msgstr "Zawartość"
":term:`Descriptors <descriptor>` let objects customize attribute lookup, "
"storage, and deletion."
msgid "This guide has four major sections:"
"The \"primer\" gives a basic overview, moving gently from simple examples, "
"adding one feature at a time.  Start here if you're new to descriptors."
"The second section shows a complete, practical descriptor example.  If you "
"already know the basics, start there."
"The third section provides a more technical tutorial that goes into the "
"detailed mechanics of how descriptors work.  Most people don't need this "
"level of detail."
"The last section has pure Python equivalents for built-in descriptors that "
"are written in C.  Read this if you're curious about how functions turn into "
"bound methods or about the implementation of common tools like :func:"
"`classmethod`, :func:`staticmethod`, :func:`property`, and :term:`__slots__`."
msgid "Primer"
"In this primer, we start with the most basic possible example and then we'll "
"add new capabilities one by one."
msgid "Simple example: A descriptor that returns a constant"
"The :class:`Ten` class is a descriptor whose :meth:`__get__` method always "
"returns the constant ``10``:"
"To use the descriptor, it must be stored as a class variable in another "
"An interactive session shows the difference between normal attribute lookup "
"and descriptor lookup:"
"In the ``a.x`` attribute lookup, the dot operator finds ``'x': 5`` in the "
"class dictionary.  In the ``a.y`` lookup, the dot operator finds a "
"descriptor instance, recognized by its ``__get__`` method. Calling that "
"method returns ``10``."
"Note that the value ``10`` is not stored in either the class dictionary or "
"the instance dictionary.  Instead, the value ``10`` is computed on demand."
"This example shows how a simple descriptor works, but it isn't very useful. "
"For retrieving constants, normal attribute lookup would be better."
"In the next section, we'll create something more useful, a dynamic lookup."
msgid "Dynamic lookups"
"Interesting descriptors typically run computations instead of returning "
"constants:"
"An interactive session shows that the lookup is dynamic — it computes "
"different, updated answers each time::"
"Besides showing how descriptors can run computations, this example also "
"reveals the purpose of the parameters to :meth:`__get__`.  The *self* "
"parameter is *size*, an instance of *DirectorySize*.  The *obj* parameter is "
"either *g* or *s*, an instance of *Directory*.  It is the *obj* parameter "
"that lets the :meth:`__get__` method learn the target directory.  The "
"*objtype* parameter is the class *Directory*."
msgid "Managed attributes"
"A popular use for descriptors is managing access to instance data.  The "
"descriptor is assigned to a public attribute in the class dictionary while "
"the actual data is stored as a private attribute in the instance "
"dictionary.  The descriptor's :meth:`__get__` and :meth:`__set__` methods "
"are triggered when the public attribute is accessed."
"In the following example, *age* is the public attribute and *_age* is the "
"private attribute.  When the public attribute is accessed, the descriptor "
"logs the lookup or update:"
"An interactive session shows that all access to the managed attribute *age* "
"is logged, but that the regular attribute *name* is not logged:"
"One major issue with this example is that the private name *_age* is "
"hardwired in the *LoggedAgeAccess* class.  That means that each instance can "
"only have one logged attribute and that its name is unchangeable.  In the "
"next example, we'll fix that problem."
msgid "Customized names"
"When a class uses descriptors, it can inform each descriptor about which "
"variable name was used."
"In this example, the :class:`Person` class has two descriptor instances, "
"*name* and *age*.  When the :class:`Person` class is defined, it makes a "
"callback to :meth:`__set_name__` in *LoggedAccess* so that the field names "
"can be recorded, giving each descriptor its own *public_name* and "
"*private_name*:"
"An interactive session shows that the :class:`Person` class has called :meth:"
"`__set_name__` so that the field names would be recorded.  Here we call :"
"func:`vars` to look up the descriptor without triggering it:"
msgid "The new class now logs access to both *name* and *age*:"
msgid "The two *Person* instances contain only the private names:"
msgid "Closing thoughts"
"A :term:`descriptor` is what we call any object that defines :meth:"
"`__get__`, :meth:`__set__`, or :meth:`__delete__`."
"Optionally, descriptors can have a :meth:`__set_name__` method.  This is "
"only used in cases where a descriptor needs to know either the class where "
"it was created or the name of class variable it was assigned to.  (This "
"method, if present, is called even if the class is not a descriptor.)"
"Descriptors get invoked by the dot operator during attribute lookup.  If a "
"descriptor is accessed indirectly with ``vars(some_class)"
"[descriptor_name]``, the descriptor instance is returned without invoking it."
"Descriptors only work when used as class variables.  When put in instances, "
"they have no effect."
"The main motivation for descriptors is to provide a hook allowing objects "
"stored in class variables to control what happens during attribute lookup."
"Traditionally, the calling class controls what happens during lookup. "
"Descriptors invert that relationship and allow the data being looked-up to "
"have a say in the matter."
"Descriptors are used throughout the language.  It is how functions turn into "
"bound methods.  Common tools like :func:`classmethod`, :func:"
"`staticmethod`, :func:`property`, and :func:`functools.cached_property` are "
"all implemented as descriptors."
msgid "Complete Practical Example"
"In this example, we create a practical and powerful tool for locating "
"notoriously hard to find data corruption bugs."
msgid "Validator class"
"A validator is a descriptor for managed attribute access.  Prior to storing "
"any data, it verifies that the new value meets various type and range "
"restrictions.  If those restrictions aren't met, it raises an exception to "
"prevent data corruption at its source."
"This :class:`Validator` class is both an :term:`abstract base class` and a "
"managed attribute descriptor:"
"Custom validators need to inherit from :class:`Validator` and must supply a :"
"meth:`validate` method to test various restrictions as needed."
msgid "Custom validators"
msgid "Here are three practical data validation utilities:"
":class:`OneOf` verifies that a value is one of a restricted set of options."
":class:`Number` verifies that a value is either an :class:`int` or :class:"
"`float`.  Optionally, it verifies that a value is between a given minimum or "
":class:`String` verifies that a value is a :class:`str`.  Optionally, it "
"validates a given minimum or maximum length.  It can validate a user-defined "
"`predicate <https://en.wikipedia.org/wiki/Predicate_(mathematical_logic)>`_ "
msgid "Practical application"
msgid "Here's how the data validators can be used in a real class:"
msgid "The descriptors prevent invalid instances from being created:"
msgid "Technical Tutorial"
"What follows is a more technical tutorial for the mechanics and details of "
"how descriptors work."
msgid "Abstract"
msgstr "Streszczenie"
"Defines descriptors, summarizes the protocol, and shows how descriptors are "
"called.  Provides an example showing how object relational mappings work."
"Learning about descriptors not only provides access to a larger toolset, it "
"creates a deeper understanding of how Python works."
msgid "Definition and introduction"
"In general, a descriptor is an attribute value that has one of the methods "
"in the descriptor protocol.  Those methods are :meth:`__get__`, :meth:"
"`__set__`, and :meth:`__delete__`.  If any of those methods are defined for "
"an attribute, it is said to be a :term:`descriptor`."
"The default behavior for attribute access is to get, set, or delete the "
"attribute from an object's dictionary.  For instance, ``a.x`` has a lookup "
"chain starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and "
"continuing through the method resolution order of ``type(a)``. If the looked-"
"up value is an object defining one of the descriptor methods, then Python "
"may override the default behavior and invoke the descriptor method instead. "
"Where this occurs in the precedence chain depends on which descriptor "
"methods were defined."
"Descriptors are a powerful, general purpose protocol.  They are the "
"mechanism behind properties, methods, static methods, class methods, and :"
"func:`super()`.  They are used throughout Python itself.  Descriptors "
"simplify the underlying C code and offer a flexible set of new tools for "
"everyday Python programs."
msgid "Descriptor protocol"
msgid "``descr.__get__(self, obj, type=None) -> value``"
msgid "``descr.__set__(self, obj, value) -> None``"
msgid "``descr.__delete__(self, obj) -> None``"
"That is all there is to it.  Define any of these methods and an object is "
"considered a descriptor and can override default behavior upon being looked "
"up as an attribute."
"If an object defines :meth:`__set__` or :meth:`__delete__`, it is considered "
"a data descriptor.  Descriptors that only define :meth:`__get__` are called "
"non-data descriptors (they are often used for methods but other uses are "
"possible)."
"Data and non-data descriptors differ in how overrides are calculated with "
"respect to entries in an instance's dictionary.  If an instance's dictionary "
"has an entry with the same name as a data descriptor, the data descriptor "
"takes precedence.  If an instance's dictionary has an entry with the same "
"name as a non-data descriptor, the dictionary entry takes precedence."
"To make a read-only data descriptor, define both :meth:`__get__` and :meth:"
"`__set__` with the :meth:`__set__` raising an :exc:`AttributeError` when "
"called.  Defining the :meth:`__set__` method with an exception raising "
"placeholder is enough to make it a data descriptor."
msgid "Overview of descriptor invocation"
"A descriptor can be called directly with ``desc.__get__(obj)`` or ``desc."
"__get__(None, cls)``."
"But it is more common for a descriptor to be invoked automatically from "
"attribute access."
"The expression ``obj.x`` looks up the attribute ``x`` in the chain of "
"namespaces for ``obj``.  If the search finds a descriptor outside of the "
"instance ``__dict__``, its :meth:`__get__` method is invoked according to "
"the precedence rules listed below."
"The details of invocation depend on whether ``obj`` is an object, class, or "
"instance of super."
msgid "Invocation from an instance"
"Instance lookup scans through a chain of namespaces giving data descriptors "
"the highest priority, followed by instance variables, then non-data "
"descriptors, then class variables, and lastly :meth:`__getattr__` if it is "
"provided."
"If a descriptor is found for ``a.x``, then it is invoked with: ``desc."
"__get__(a, type(a))``."
"The logic for a dotted lookup is in :meth:`object.__getattribute__`.  Here "
"is a pure Python equivalent:"
"Note, there is no :meth:`__getattr__` hook in the :meth:`__getattribute__` "
"code.  That is why calling :meth:`__getattribute__` directly or with "
"``super().__getattribute__`` will bypass :meth:`__getattr__` entirely."
"Instead, it is the dot operator and the :func:`getattr` function that are "
"responsible for invoking :meth:`__getattr__` whenever :meth:"
"`__getattribute__` raises an :exc:`AttributeError`.  Their logic is "
"encapsulated in a helper function:"
msgid "Invocation from a class"
"The logic for a dotted lookup such as ``A.x`` is in :meth:`type."
"__getattribute__`.  The steps are similar to those for :meth:`object."
"__getattribute__` but the instance dictionary lookup is replaced by a search "
"through the class's :term:`method resolution order`."
msgid "If a descriptor is found, it is invoked with ``desc.__get__(None, A)``."
"The full C implementation can be found in :c:func:`type_getattro()` and :c:"
"func:`_PyType_Lookup()` in :source:`Objects/typeobject.c`."
msgid "Invocation from super"
"The logic for super's dotted lookup is in the :meth:`__getattribute__` "
"method for object returned by :class:`super()`."
"A dotted lookup such as ``super(A, obj).m`` searches ``obj.__class__."
"__mro__`` for the base class ``B`` immediately following ``A`` and then "
"returns ``B.__dict__['m'].__get__(obj, A)``.  If not a descriptor, ``m`` is "
"returned unchanged."
"The full C implementation can be found in :c:func:`super_getattro()` in :"
"source:`Objects/typeobject.c`.  A pure Python equivalent can be found in "
"`Guido's Tutorial <https://www.python.org/download/releases/2.2.3/descrintro/"
"#cooperation>`_."
msgid "Summary of invocation logic"
"The mechanism for descriptors is embedded in the :meth:`__getattribute__()` "
"methods for :class:`object`, :class:`type`, and :func:`super`."
msgid "The important points to remember are:"
msgid "Descriptors are invoked by the :meth:`__getattribute__` method."
"Classes inherit this machinery from :class:`object`, :class:`type`, or :func:"
"Overriding :meth:`__getattribute__` prevents automatic descriptor calls "
"because all the descriptor logic is in that method."
":meth:`object.__getattribute__` and :meth:`type.__getattribute__` make "
"different calls to :meth:`__get__`.  The first includes the instance and may "
"include the class.  The second puts in ``None`` for the instance and always "
"includes the class."
msgid "Data descriptors always override instance dictionaries."
msgid "Non-data descriptors may be overridden by instance dictionaries."
msgid "Automatic name notification"
"Sometimes it is desirable for a descriptor to know what class variable name "
"it was assigned to.  When a new class is created, the :class:`type` "
"metaclass scans the dictionary of the new class.  If any of the entries are "
"descriptors and if they define :meth:`__set_name__`, that method is called "
"with two arguments.  The *owner* is the class where the descriptor is used, "
"and the *name* is the class variable the descriptor was assigned to."
"The implementation details are in :c:func:`type_new()` and :c:func:"
"`set_names()` in :source:`Objects/typeobject.c`."
"Since the update logic is in :meth:`type.__new__`, notifications only take "
"place at the time of class creation.  If descriptors are added to the class "
"afterwards, :meth:`__set_name__` will need to be called manually."
msgid "ORM example"
"The following code is a simplified skeleton showing how data descriptors "
"could be used to implement an `object relational mapping <https://en."
"wikipedia.org/wiki/Object%E2%80%93relational_mapping>`_."
"The essential idea is that the data is stored in an external database.  The "
"Python instances only hold keys to the database's tables.  Descriptors take "
"care of lookups or updates:"
"We can use the :class:`Field` class to define `models <https://en.wikipedia."
"org/wiki/Database_model>`_ that describe the schema for each table in a "
"database:"
msgid "To use the models, first connect to the database::"
"An interactive session shows how data is retrieved from the database and how "
"it can be updated:"
msgid "Pure Python Equivalents"
"The descriptor protocol is simple and offers exciting possibilities.  "
"Several use cases are so common that they have been prepackaged into built-"
"in tools. Properties, bound methods, static methods, class methods, and "
"\\_\\_slots\\_\\_ are all based on the descriptor protocol."
msgid "Properties"
"Calling :func:`property` is a succinct way of building a data descriptor "
"that triggers a function call upon access to an attribute.  Its signature "
"The documentation shows a typical use to define a managed attribute ``x``:"
"To see how :func:`property` is implemented in terms of the descriptor "
"protocol, here is a pure Python equivalent:"
"The :func:`property` builtin helps whenever a user interface has granted "
"attribute access and then subsequent changes require the intervention of a "
"For instance, a spreadsheet class may grant access to a cell value through "
"``Cell('b10').value``. Subsequent improvements to the program require the "
"cell to be recalculated on every access; however, the programmer does not "
"want to affect existing client code accessing the attribute directly.  The "
"solution is to wrap access to the value attribute in a property data "
"descriptor:"
"Either the built-in :func:`property` or our :func:`Property` equivalent "
"would work in this example."
msgid "Functions and methods"
"Python's object oriented features are built upon a function based "
"environment. Using non-data descriptors, the two are merged seamlessly."
"Functions stored in class dictionaries get turned into methods when invoked. "
"Methods only differ from regular functions in that the object instance is "
"prepended to the other arguments.  By convention, the instance is called "
"*self* but could be called *this* or any other variable name."
"Methods can be created manually with :class:`types.MethodType` which is "
"roughly equivalent to:"
"To support automatic creation of methods, functions include the :meth:"
"`__get__` method for binding methods during attribute access.  This means "
"that functions are non-data descriptors that return bound methods during "
"dotted lookup from an instance.  Here's how it works:"
"Running the following class in the interpreter shows how the function "
"descriptor works in practice:"
"The function has a :term:`qualified name` attribute to support introspection:"
"Accessing the function through the class dictionary does not invoke :meth:"
"`__get__`.  Instead, it just returns the underlying function object::"
"Dotted access from a class calls :meth:`__get__` which just returns the "
"underlying function unchanged::"
"The interesting behavior occurs during dotted access from an instance.  The "
"dotted lookup calls :meth:`__get__` which returns a bound method object::"
"Internally, the bound method stores the underlying function and the bound "
"instance::"
"If you have ever wondered where *self* comes from in regular methods or "
"where *cls* comes from in class methods, this is it!"
msgid "Kinds of methods"
"Non-data descriptors provide a simple mechanism for variations on the usual "
"patterns of binding functions into methods."
"To recap, functions have a :meth:`__get__` method so that they can be "
"converted to a method when accessed as attributes.  The non-data descriptor "
"transforms an ``obj.f(*args)`` call into ``f(obj, *args)``.  Calling ``cls."
"f(*args)`` becomes ``f(*args)``."
msgid "This chart summarizes the binding and its two most useful variants:"
msgid "Transformation"
msgid "Called from an object"
msgid "Called from a class"
msgid "function"
msgstr "funkcja"
msgid "f(obj, \\*args)"
msgid "f(\\*args)"
msgstr "f(\\*args)"
msgid "staticmethod"
msgid "classmethod"
msgid "f(type(obj), \\*args)"
msgid "f(cls, \\*args)"
msgid "Static methods"
"Static methods return the underlying function without changes.  Calling "
"either ``c.f`` or ``C.f`` is the equivalent of a direct lookup into ``object."
"__getattribute__(c, \"f\")`` or ``object.__getattribute__(C, \"f\")``. As a "
"result, the function becomes identically accessible from either an object or "
"Good candidates for static methods are methods that do not reference the "
"``self`` variable."
"For instance, a statistics package may include a container class for "
"experimental data.  The class provides normal methods for computing the "
"average, mean, median, and other descriptive statistics that depend on the "
"data. However, there may be useful functions which are conceptually related "
"but do not depend on the data.  For instance, ``erf(x)`` is handy conversion "
"routine that comes up in statistical work but does not directly depend on a "
"particular dataset. It can be called either from an object or the class:  "
"``s.erf(1.5) --> .9332`` or ``Sample.erf(1.5) --> .9332``."
"Since static methods return the underlying function with no changes, the "
"example calls are unexciting:"
"Using the non-data descriptor protocol, a pure Python version of :func:"
"`staticmethod` would look like this:"
msgid "Class methods"
"Unlike static methods, class methods prepend the class reference to the "
"argument list before calling the function.  This format is the same for "
"whether the caller is an object or a class:"
"This behavior is useful whenever the method only needs to have a class "
"reference and does not rely on data stored in a specific instance.  One use "
"for class methods is to create alternate class constructors.  For example, "
"the classmethod :func:`dict.fromkeys` creates a new dictionary from a list "
"of keys.  The pure Python equivalent is:"
msgid "Now a new dictionary of unique keys can be constructed like this:"
"Using the non-data descriptor protocol, a pure Python version of :func:"
"`classmethod` would look like this:"
"The code path for ``hasattr(type(self.f), '__get__')`` was added in Python "
"3.9 and makes it possible for :func:`classmethod` to support chained "
"decorators.  For example, a classmethod and property could be chained "
"together:"
msgid "Member objects and __slots__"
"When a class defines ``__slots__``, it replaces instance dictionaries with a "
"fixed-length array of slot values.  From a user point of view that has "
"several effects:"
"1. Provides immediate detection of bugs due to misspelled attribute "
"assignments.  Only attribute names specified in ``__slots__`` are allowed:"
"2. Helps create immutable objects where descriptors manage access to private "
"attributes stored in ``__slots__``:"
"3. Saves memory.  On a 64-bit Linux build, an instance with two attributes "
"takes 48 bytes with ``__slots__`` and 152 bytes without.  This `flyweight "
"design pattern <https://en.wikipedia.org/wiki/Flyweight_pattern>`_ likely "
"only matters when a large number of instances are going to be created."
"4. Improves speed.  Reading instance variables is 35% faster with "
"``__slots__`` (as measured with Python 3.10 on an Apple M1 processor)."
"5. Blocks tools like :func:`functools.cached_property` which require an "
"instance dictionary to function correctly:"
"It is not possible to create an exact drop-in pure Python version of "
"``__slots__`` because it requires direct access to C structures and control "
"over object memory allocation.  However, we can build a mostly faithful "
"simulation where the actual C structure for slots is emulated by a private "
"``_slotvalues`` list.  Reads and writes to that private structure are "
"managed by member descriptors:"
"The :meth:`type.__new__` method takes care of adding member objects to class "
"variables:"
"The :meth:`object.__new__` method takes care of creating instances that have "
"slots instead of an instance dictionary.  Here is a rough simulation in pure "
"To use the simulation in a real class, just inherit from :class:`Object` and "
"set the :term:`metaclass` to :class:`Type`:"
"At this point, the metaclass has loaded member objects for *x* and *y*::"
"When instances are created, they have a ``slot_values`` list where the "
"attributes are stored:"
msgid "Misspelled or unassigned attributes will raise an exception:"
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

FilesExpand file tree

descriptor.po

Latest commit

History

descriptor.po

File metadata and controls
