|
| 1 | +# SOME DESCRIPTIVE TITLE. |
| 2 | +# Copyright (C) 2001-2025, Python Software Foundation |
| 3 | +# This file is distributed under the same license as the Python package. |
| 4 | +# FIRST AUTHOR <EMAIL@ADDRESS>, 2025. |
| 5 | +# |
| 6 | +#, fuzzy |
| 7 | +msgid "" |
| 8 | +msgstr "" |
| 9 | +"Project-Id-Version: Python 3.13\n" |
| 10 | +"Report-Msgid-Bugs-To: \n" |
| 11 | +"POT-Creation-Date: 2025-03-04 13:08+0200\n" |
| 12 | +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" |
| 13 | +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" |
| 14 | +"Language: ro\n" |
| 15 | +"Language-Team: ro <LL@li.org>\n" |
| 16 | +"Plural-Forms: nplurals=3; plural=(n==1 ? 0 : (n==0 || (n%100 > 0 && n%100" |
| 17 | +" < 20)) ? 1 : 2);\n" |
| 18 | +"MIME-Version: 1.0\n" |
| 19 | +"Content-Type: text/plain; charset=utf-8\n" |
| 20 | +"Content-Transfer-Encoding: 8bit\n" |
| 21 | +"Generated-By: Babel 2.17.0\n" |
| 22 | + |
| 23 | +#: ../../howto/annotations.rst:5 |
| 24 | +msgid "Annotations Best Practices" |
| 25 | +msgstr "" |
| 26 | + |
| 27 | +#: ../../howto/annotations.rst |
| 28 | +msgid "author" |
| 29 | +msgstr "" |
| 30 | + |
| 31 | +#: ../../howto/annotations.rst:7 |
| 32 | +msgid "Larry Hastings" |
| 33 | +msgstr "" |
| 34 | + |
| 35 | +#: ../../howto/annotations.rst:-1 |
| 36 | +msgid "Abstract" |
| 37 | +msgstr "" |
| 38 | + |
| 39 | +#: ../../howto/annotations.rst:11 |
| 40 | +msgid "" |
| 41 | +"This document is designed to encapsulate the best practices for working " |
| 42 | +"with annotations dicts. If you write Python code that examines " |
| 43 | +"``__annotations__`` on Python objects, we encourage you to follow the " |
| 44 | +"guidelines described below." |
| 45 | +msgstr "" |
| 46 | + |
| 47 | +#: ../../howto/annotations.rst:16 |
| 48 | +msgid "" |
| 49 | +"The document is organized into four sections: best practices for " |
| 50 | +"accessing the annotations of an object in Python versions 3.10 and newer," |
| 51 | +" best practices for accessing the annotations of an object in Python " |
| 52 | +"versions 3.9 and older, other best practices for ``__annotations__`` that" |
| 53 | +" apply to any Python version, and quirks of ``__annotations__``." |
| 54 | +msgstr "" |
| 55 | + |
| 56 | +#: ../../howto/annotations.rst:26 |
| 57 | +msgid "" |
| 58 | +"Note that this document is specifically about working with " |
| 59 | +"``__annotations__``, not uses *for* annotations. If you're looking for " |
| 60 | +"information on how to use \"type hints\" in your code, please see the " |
| 61 | +":mod:`typing` module." |
| 62 | +msgstr "" |
| 63 | + |
| 64 | +#: ../../howto/annotations.rst:33 |
| 65 | +msgid "Accessing The Annotations Dict Of An Object In Python 3.10 And Newer" |
| 66 | +msgstr "" |
| 67 | + |
| 68 | +#: ../../howto/annotations.rst:35 |
| 69 | +msgid "" |
| 70 | +"Python 3.10 adds a new function to the standard library: " |
| 71 | +":func:`inspect.get_annotations`. In Python versions 3.10 and newer, " |
| 72 | +"calling this function is the best practice for accessing the annotations " |
| 73 | +"dict of any object that supports annotations. This function can also " |
| 74 | +"\"un-stringize\" stringized annotations for you." |
| 75 | +msgstr "" |
| 76 | + |
| 77 | +#: ../../howto/annotations.rst:42 |
| 78 | +msgid "" |
| 79 | +"If for some reason :func:`inspect.get_annotations` isn't viable for your " |
| 80 | +"use case, you may access the ``__annotations__`` data member manually. " |
| 81 | +"Best practice for this changed in Python 3.10 as well: as of Python 3.10," |
| 82 | +" ``o.__annotations__`` is guaranteed to *always* work on Python " |
| 83 | +"functions, classes, and modules. If you're certain the object you're " |
| 84 | +"examining is one of these three *specific* objects, you may simply use " |
| 85 | +"``o.__annotations__`` to get at the object's annotations dict." |
| 86 | +msgstr "" |
| 87 | + |
| 88 | +#: ../../howto/annotations.rst:52 |
| 89 | +msgid "" |
| 90 | +"However, other types of callables--for example, callables created by " |
| 91 | +":func:`functools.partial`--may not have an ``__annotations__`` attribute " |
| 92 | +"defined. When accessing the ``__annotations__`` of a possibly unknown " |
| 93 | +"object, best practice in Python versions 3.10 and newer is to call " |
| 94 | +":func:`getattr` with three arguments, for example ``getattr(o, " |
| 95 | +"'__annotations__', None)``." |
| 96 | +msgstr "" |
| 97 | + |
| 98 | +#: ../../howto/annotations.rst:60 |
| 99 | +msgid "" |
| 100 | +"Before Python 3.10, accessing ``__annotations__`` on a class that defines" |
| 101 | +" no annotations but that has a parent class with annotations would return" |
| 102 | +" the parent's ``__annotations__``. In Python 3.10 and newer, the child " |
| 103 | +"class's annotations will be an empty dict instead." |
| 104 | +msgstr "" |
| 105 | + |
| 106 | +#: ../../howto/annotations.rst:68 |
| 107 | +msgid "Accessing The Annotations Dict Of An Object In Python 3.9 And Older" |
| 108 | +msgstr "" |
| 109 | + |
| 110 | +#: ../../howto/annotations.rst:70 |
| 111 | +msgid "" |
| 112 | +"In Python 3.9 and older, accessing the annotations dict of an object is " |
| 113 | +"much more complicated than in newer versions. The problem is a design " |
| 114 | +"flaw in these older versions of Python, specifically to do with class " |
| 115 | +"annotations." |
| 116 | +msgstr "" |
| 117 | + |
| 118 | +#: ../../howto/annotations.rst:75 |
| 119 | +msgid "" |
| 120 | +"Best practice for accessing the annotations dict of other objects--" |
| 121 | +"functions, other callables, and modules--is the same as best practice for" |
| 122 | +" 3.10, assuming you aren't calling :func:`inspect.get_annotations`: you " |
| 123 | +"should use three-argument :func:`getattr` to access the object's " |
| 124 | +"``__annotations__`` attribute." |
| 125 | +msgstr "" |
| 126 | + |
| 127 | +#: ../../howto/annotations.rst:82 |
| 128 | +msgid "" |
| 129 | +"Unfortunately, this isn't best practice for classes. The problem is " |
| 130 | +"that, since ``__annotations__`` is optional on classes, and because " |
| 131 | +"classes can inherit attributes from their base classes, accessing the " |
| 132 | +"``__annotations__`` attribute of a class may inadvertently return the " |
| 133 | +"annotations dict of a *base class.* As an example::" |
| 134 | +msgstr "" |
| 135 | + |
| 136 | +#: ../../howto/annotations.rst:89 |
| 137 | +msgid "" |
| 138 | +"class Base:\n" |
| 139 | +" a: int = 3\n" |
| 140 | +" b: str = 'abc'\n" |
| 141 | +"\n" |
| 142 | +"class Derived(Base):\n" |
| 143 | +" pass\n" |
| 144 | +"\n" |
| 145 | +"print(Derived.__annotations__)" |
| 146 | +msgstr "" |
| 147 | + |
| 148 | +#: ../../howto/annotations.rst:98 |
| 149 | +msgid "This will print the annotations dict from ``Base``, not ``Derived``." |
| 150 | +msgstr "" |
| 151 | + |
| 152 | +#: ../../howto/annotations.rst:101 |
| 153 | +msgid "" |
| 154 | +"Your code will have to have a separate code path if the object you're " |
| 155 | +"examining is a class (``isinstance(o, type)``). In that case, best " |
| 156 | +"practice relies on an implementation detail of Python 3.9 and before: if " |
| 157 | +"a class has annotations defined, they are stored in the class's " |
| 158 | +":attr:`~type.__dict__` dictionary. Since the class may or may not have " |
| 159 | +"annotations defined, best practice is to call the :meth:`~dict.get` " |
| 160 | +"method on the class dict." |
| 161 | +msgstr "" |
| 162 | + |
| 163 | +#: ../../howto/annotations.rst:109 |
| 164 | +msgid "" |
| 165 | +"To put it all together, here is some sample code that safely accesses the" |
| 166 | +" ``__annotations__`` attribute on an arbitrary object in Python 3.9 and " |
| 167 | +"before::" |
| 168 | +msgstr "" |
| 169 | + |
| 170 | +#: ../../howto/annotations.rst:113 |
| 171 | +msgid "" |
| 172 | +"if isinstance(o, type):\n" |
| 173 | +" ann = o.__dict__.get('__annotations__', None)\n" |
| 174 | +"else:\n" |
| 175 | +" ann = getattr(o, '__annotations__', None)" |
| 176 | +msgstr "" |
| 177 | + |
| 178 | +#: ../../howto/annotations.rst:118 |
| 179 | +msgid "" |
| 180 | +"After running this code, ``ann`` should be either a dictionary or " |
| 181 | +"``None``. You're encouraged to double-check the type of ``ann`` using " |
| 182 | +":func:`isinstance` before further examination." |
| 183 | +msgstr "" |
| 184 | + |
| 185 | +#: ../../howto/annotations.rst:123 |
| 186 | +msgid "" |
| 187 | +"Note that some exotic or malformed type objects may not have a " |
| 188 | +":attr:`~type.__dict__` attribute, so for extra safety you may also wish " |
| 189 | +"to use :func:`getattr` to access :attr:`!__dict__`." |
| 190 | +msgstr "" |
| 191 | + |
| 192 | +#: ../../howto/annotations.rst:129 |
| 193 | +msgid "Manually Un-Stringizing Stringized Annotations" |
| 194 | +msgstr "" |
| 195 | + |
| 196 | +#: ../../howto/annotations.rst:131 |
| 197 | +msgid "" |
| 198 | +"In situations where some annotations may be \"stringized\", and you wish " |
| 199 | +"to evaluate those strings to produce the Python values they represent, it" |
| 200 | +" really is best to call :func:`inspect.get_annotations` to do this work " |
| 201 | +"for you." |
| 202 | +msgstr "" |
| 203 | + |
| 204 | +#: ../../howto/annotations.rst:137 |
| 205 | +msgid "" |
| 206 | +"If you're using Python 3.9 or older, or if for some reason you can't use " |
| 207 | +":func:`inspect.get_annotations`, you'll need to duplicate its logic. " |
| 208 | +"You're encouraged to examine the implementation of " |
| 209 | +":func:`inspect.get_annotations` in the current Python version and follow " |
| 210 | +"a similar approach." |
| 211 | +msgstr "" |
| 212 | + |
| 213 | +#: ../../howto/annotations.rst:143 |
| 214 | +msgid "" |
| 215 | +"In a nutshell, if you wish to evaluate a stringized annotation on an " |
| 216 | +"arbitrary object ``o``:" |
| 217 | +msgstr "" |
| 218 | + |
| 219 | +#: ../../howto/annotations.rst:146 |
| 220 | +msgid "" |
| 221 | +"If ``o`` is a module, use ``o.__dict__`` as the ``globals`` when calling " |
| 222 | +":func:`eval`." |
| 223 | +msgstr "" |
| 224 | + |
| 225 | +#: ../../howto/annotations.rst:148 |
| 226 | +msgid "" |
| 227 | +"If ``o`` is a class, use ``sys.modules[o.__module__].__dict__`` as the " |
| 228 | +"``globals``, and ``dict(vars(o))`` as the ``locals``, when calling " |
| 229 | +":func:`eval`." |
| 230 | +msgstr "" |
| 231 | + |
| 232 | +#: ../../howto/annotations.rst:151 |
| 233 | +msgid "" |
| 234 | +"If ``o`` is a wrapped callable using :func:`functools.update_wrapper`, " |
| 235 | +":func:`functools.wraps`, or :func:`functools.partial`, iteratively unwrap" |
| 236 | +" it by accessing either ``o.__wrapped__`` or ``o.func`` as appropriate, " |
| 237 | +"until you have found the root unwrapped function." |
| 238 | +msgstr "" |
| 239 | + |
| 240 | +#: ../../howto/annotations.rst:155 |
| 241 | +msgid "" |
| 242 | +"If ``o`` is a callable (but not a class), use :attr:`o.__globals__ " |
| 243 | +"<function.__globals__>` as the globals when calling :func:`eval`." |
| 244 | +msgstr "" |
| 245 | + |
| 246 | +#: ../../howto/annotations.rst:159 |
| 247 | +msgid "" |
| 248 | +"However, not all string values used as annotations can be successfully " |
| 249 | +"turned into Python values by :func:`eval`. String values could " |
| 250 | +"theoretically contain any valid string, and in practice there are valid " |
| 251 | +"use cases for type hints that require annotating with string values that " |
| 252 | +"specifically *can't* be evaluated. For example:" |
| 253 | +msgstr "" |
| 254 | + |
| 255 | +#: ../../howto/annotations.rst:166 |
| 256 | +msgid "" |
| 257 | +":pep:`604` union types using ``|``, before support for this was added to " |
| 258 | +"Python 3.10." |
| 259 | +msgstr "" |
| 260 | + |
| 261 | +#: ../../howto/annotations.rst:168 |
| 262 | +msgid "" |
| 263 | +"Definitions that aren't needed at runtime, only imported when " |
| 264 | +":const:`typing.TYPE_CHECKING` is true." |
| 265 | +msgstr "" |
| 266 | + |
| 267 | +#: ../../howto/annotations.rst:171 |
| 268 | +msgid "" |
| 269 | +"If :func:`eval` attempts to evaluate such values, it will fail and raise " |
| 270 | +"an exception. So, when designing a library API that works with " |
| 271 | +"annotations, it's recommended to only attempt to evaluate string values " |
| 272 | +"when explicitly requested to by the caller." |
| 273 | +msgstr "" |
| 274 | + |
| 275 | +#: ../../howto/annotations.rst:179 |
| 276 | +msgid "Best Practices For ``__annotations__`` In Any Python Version" |
| 277 | +msgstr "" |
| 278 | + |
| 279 | +#: ../../howto/annotations.rst:181 |
| 280 | +msgid "" |
| 281 | +"You should avoid assigning to the ``__annotations__`` member of objects " |
| 282 | +"directly. Let Python manage setting ``__annotations__``." |
| 283 | +msgstr "" |
| 284 | + |
| 285 | +#: ../../howto/annotations.rst:184 |
| 286 | +msgid "" |
| 287 | +"If you do assign directly to the ``__annotations__`` member of an object," |
| 288 | +" you should always set it to a ``dict`` object." |
| 289 | +msgstr "" |
| 290 | + |
| 291 | +#: ../../howto/annotations.rst:187 |
| 292 | +msgid "" |
| 293 | +"If you directly access the ``__annotations__`` member of an object, you " |
| 294 | +"should ensure that it's a dictionary before attempting to examine its " |
| 295 | +"contents." |
| 296 | +msgstr "" |
| 297 | + |
| 298 | +#: ../../howto/annotations.rst:191 |
| 299 | +msgid "You should avoid modifying ``__annotations__`` dicts." |
| 300 | +msgstr "" |
| 301 | + |
| 302 | +#: ../../howto/annotations.rst:193 |
| 303 | +msgid "You should avoid deleting the ``__annotations__`` attribute of an object." |
| 304 | +msgstr "" |
| 305 | + |
| 306 | +#: ../../howto/annotations.rst:198 |
| 307 | +msgid "``__annotations__`` Quirks" |
| 308 | +msgstr "" |
| 309 | + |
| 310 | +#: ../../howto/annotations.rst:200 |
| 311 | +msgid "" |
| 312 | +"In all versions of Python 3, function objects lazy-create an annotations " |
| 313 | +"dict if no annotations are defined on that object. You can delete the " |
| 314 | +"``__annotations__`` attribute using ``del fn.__annotations__``, but if " |
| 315 | +"you then access ``fn.__annotations__`` the object will create a new empty" |
| 316 | +" dict that it will store and return as its annotations. Deleting the " |
| 317 | +"annotations on a function before it has lazily created its annotations " |
| 318 | +"dict will throw an ``AttributeError``; using ``del fn.__annotations__`` " |
| 319 | +"twice in a row is guaranteed to always throw an ``AttributeError``." |
| 320 | +msgstr "" |
| 321 | + |
| 322 | +#: ../../howto/annotations.rst:210 |
| 323 | +msgid "" |
| 324 | +"Everything in the above paragraph also applies to class and module " |
| 325 | +"objects in Python 3.10 and newer." |
| 326 | +msgstr "" |
| 327 | + |
| 328 | +#: ../../howto/annotations.rst:213 |
| 329 | +msgid "" |
| 330 | +"In all versions of Python 3, you can set ``__annotations__`` on a " |
| 331 | +"function object to ``None``. However, subsequently accessing the " |
| 332 | +"annotations on that object using ``fn.__annotations__`` will lazy-create " |
| 333 | +"an empty dictionary as per the first paragraph of this section. This is " |
| 334 | +"*not* true of modules and classes, in any Python version; those objects " |
| 335 | +"permit setting ``__annotations__`` to any Python value, and will retain " |
| 336 | +"whatever value is set." |
| 337 | +msgstr "" |
| 338 | + |
| 339 | +#: ../../howto/annotations.rst:221 |
| 340 | +msgid "" |
| 341 | +"If Python stringizes your annotations for you (using ``from __future__ " |
| 342 | +"import annotations``), and you specify a string as an annotation, the " |
| 343 | +"string will itself be quoted. In effect the annotation is quoted " |
| 344 | +"*twice.* For example::" |
| 345 | +msgstr "" |
| 346 | + |
| 347 | +#: ../../howto/annotations.rst:227 |
| 348 | +msgid "" |
| 349 | +"from __future__ import annotations\n" |
| 350 | +"def foo(a: \"str\"): pass\n" |
| 351 | +"\n" |
| 352 | +"print(foo.__annotations__)" |
| 353 | +msgstr "" |
| 354 | + |
| 355 | +#: ../../howto/annotations.rst:232 |
| 356 | +#, python-brace-format |
| 357 | +msgid "" |
| 358 | +"This prints ``{'a': \"'str'\"}``. This shouldn't really be considered a " |
| 359 | +"\"quirk\"; it's mentioned here simply because it might be surprising." |
| 360 | +msgstr "" |
| 361 | + |
0 commit comments