{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "api", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Any class with trait attributes must inherit from " }, { "__type": "InlineRole", "__tag": 4003, "value": "HasTraits", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "You then declare the trait attributes on the class like this " } ] }, { "__type": "Code", "__tag": 4050, "value": "from traitlets import HasTraits, Int, Unicode\n\nclass Requester(HasTraits):\n url = Unicode()\n timeout = Int(30) # 30 will be the default value", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For the available trait types and the arguments you can give them, see " }, { "__type": "CrossRef", "__tag": 4002, "value": "trait_types", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "trait_types" }, "kind": "docs" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Traitlets API reference" } ], "level": 0, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To calculate a default value dynamically, decorate a method of your class with " }, { "__type": "InlineCode", "__tag": 4051, "value": "@default({traitname})" }, { "__type": "Text", "__tag": 4046, "value": ". This method will be called on the instance, and should return the default value. For example " } ] }, { "__type": "Code", "__tag": 4050, "value": "import getpass\n\nclass Identity(HasTraits):\n username = Unicode()\n\n @default('username')\n def _username_default(self):\n return getpass.getuser()", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Dynamic default values" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To do something when a trait attribute is changed, decorate a method with " }, { "__type": "CrossRef", "__tag": 4002, "value": "traitlets.observe", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "traitlets", "version": "*", "kind": "api", "path": "traitlets.traitlets:observe" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ". The method will be called with a single argument, a dictionary of the form " } ] }, { "__type": "Code", "__tag": 4050, "value": "{\n 'owner': object, # The HasTraits instance\n 'new': 6, # The new value\n 'old': 5, # The old value\n 'name': \"foo\", # The name of the changed trait\n 'type': 'change', # The event type of the notification, usually 'change'\n}", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For example " } ] }, { "__type": "Code", "__tag": 4050, "value": "from traitlets import HasTraits, Integer, observe\n\nclass TraitletsExample(HasTraits):\n num = Integer(5, help=\"a number\").tag(config=True)\n\n @observe('num')\n def _num_changed(self, change):\n print(\"{name} changed from {old} to {new}\".format(**change))", "execution_status": null }, { "__type": "Admonition", "__tag": 4056, "kind": "versionchanged", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionchanged 4.1" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": "_{trait}_changed" }, { "__type": "Text", "__tag": 4046, "value": " magic method-name approach is deprecated." } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "You can also add callbacks to a trait dynamically:" } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If a trait attribute with a dynamic default value has another value set before it is used, the default will not be calculated. Any callbacks on that trait will will fire, and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "old_value" } ] }, { "__type": "Text", "__tag": 4046, "value": " will be " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Callbacks when trait attributes change" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Validator methods can be used to enforce certain aspects of a property. These are called on proposed changes, and can raise a TraitError if the change should be rejected, or coerce the value if it should be accepted with some modification. This can be useful for things such as ensuring a path string is always absolute, or check if it points to an existing directory." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For example " } ] }, { "__type": "Code", "__tag": 4050, "value": "from traitlets import HasTraits, Unicode, validate, TraitError\n\nclass TraitletsExample(HasTraits):\n path = Unicode('', help=\"a path\")\n\n @validate('path')\n def _check_prime(self, proposal):\n path = proposal['value']\n if not path.endswith('/'):\n # ensure path always has trailing /\n path = path + '/'\n if not os.path.exists(path):\n raise TraitError(\"path %r does not exist\" % path)\n return path", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Validating proposed changes" } ], "level": 1, "target": null } ], "local_refs": [] }