{"id":31782271,"url":"https://github.com/zopefoundation/grokcore.component","last_synced_at":"2025-10-10T09:18:06.876Z","repository":{"id":7197521,"uuid":"8501817","full_name":"zopefoundation/grokcore.component","owner":"zopefoundation","description":"Grok-like configuration for basic components (adapters, utilities, subscribers)","archived":false,"fork":false,"pushed_at":"2025-06-18T06:25:03.000Z","size":1351,"stargazers_count":1,"open_issues_count":0,"forks_count":3,"subscribers_count":61,"default_branch":"master","last_synced_at":"2025-10-04T21:37:38.483Z","etag":null,"topics":["maintained"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zopefoundation.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-03-01T13:25:26.000Z","updated_at":"2025-06-18T06:25:54.000Z","dependencies_parsed_at":"2024-06-21T16:53:07.460Z","dependency_job_id":null,"html_url":"https://github.com/zopefoundation/grokcore.component","commit_stats":{"total_commits":274,"total_committers":22,"mean_commits":"12.454545454545455","dds":0.7481751824817517,"last_synced_commit":"21629f8654961d1b4939bca8ad6b8463c13a6574"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/zopefoundation/grokcore.component","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zopefoundation%2Fgrokcore.component","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zopefoundation%2Fgrokcore.component/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zopefoundation%2Fgrokcore.component/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zopefoundation%2Fgrokcore.component/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zopefoundation","download_url":"https://codeload.github.com/zopefoundation/grokcore.component/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zopefoundation%2Fgrokcore.component/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001890,"owners_count":26083197,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["maintained"],"created_at":"2025-10-10T09:18:01.217Z","updated_at":"2025-10-10T09:18:06.871Z","avatar_url":"https://github.com/zopefoundation.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"This package provides base classes of basic component types for the\nZope Component Architecture, as well as means for configuring and\nregistering them directly in Python (without ZCML).\n\n.. contents::\n\nHow to set up ``grokcore.component``\n====================================\n\nIn the following we assume you're writing or extending an application\nthat does bootstrap configuration using ZCML.  There's always a single\nZCML file that is executed when the application is started, which then\nincludes everything else.  Let's assume this file is called\n``site.zcml`` (that's what it's called in Zope), so that file is what\nwe'll be editing.\n\nIn order to register the components that you wrote using the base\nclasses and directives available from ``grokcore.component``, we'll\nuse the ``\u003cgrok:grok /\u003e`` ZCML directive.  But before we can use it,\nwe need to make sure it's available to the ZCML machinery.  We do this\nby including the meta configuration from ``grokcore.component``::\n\n  \u003cinclude package=\"grokcore.component\" file=\"meta.zcml\" /\u003e\n\nPut this line somewhere to the top of ``site.zcml``, next to other\nmeta configuration includes.  Now, further down the line, we can tell\nthe machinery in ``grokcore.component`` to register all components in\nyour package (let's say it's called ``helloworld``)::\n\n  \u003cgrok:grok package=\"helloworld\" /\u003e\n\nTo sum up, your ``site.zcml`` file should look like something like this::\n\n  \u003cconfigure\n      xmlns=\"http://namespaces.zope.org/zope\"\n      xmlns:grok=\"http://namespaces.zope.org/grok\"\u003e\n\n    \u003c!-- do the meta configuration to make the ZCML directives available --\u003e\n    \u003cinclude package=\"zope.foobar\" file=\"meta.zcml\" /\u003e\n    \u003cinclude package=\"zope.frobnaz\" file=\"meta.zcml\" /\u003e\n    \u003cinclude package=\"grokcore.component\" file=\"meta.zcml\" /\u003e\n\n    \u003c!-- now load the configuration of packages that we depend on --\u003e\n    \u003cinclude package=\"zope.barfoo\" /\u003e\n    \u003cinclude package=\"zope.somethingorother\" /\u003e\n\n    \u003c!-- finally load my components which are based on grokcore.component --\u003e\n    \u003cgrok:grok package=\"helloworld\" /\u003e\n\n  \u003c/configure\u003e\n\nThere is an optional ``exclude`` on the `grok` directive. It allows to specify\nnames of packages or modules that if encountered won't be grokked. These\nnames might contain unix shell-style wildcards.\n\n`implementer()` versus `implements()`\n=====================================\n\nNote how the Python 3 compatibility brings a change in how the\n`grokcore.component.implements()` *directive* works. When using this directive\nyou now have to make sure the component is grokkked, to have the underlying\nmechanism to take effect.\n\nAlternatively you could start to use the `grokcore.component.implementer()`\n*class decorator* instead. This will do the same thing, but does not require\nyour component to be grokkked and still have your component declare it\nimplements the given interface.\n\nExamples\n========\n\nAdapter\n-------\n\nHere's a simple adapter that may be useful in Zope.  It extracts the\nlanguages that a user prefers from the request::\n\n  import grokcore.component\n  from zope.publisher.interfaces.browser import IBrowserRequest\n  from zope.i18n.interfaces import IUserPreferredLanguages\n\n  class CookieLanguage(grokcore.component.Adapter):\n      \"\"\"Extract the preferred language from a cookie\"\"\"\n      grokcore.component.context(IBrowserRequest)\n      grokcore.component.implements(IUserPreferredLanguages)\n\n      # No need to implement __init__, it's already provided by the base class.\n\n      def getPreferredLanguages(self):\n          # This an adapter for the request, so self.context is the request.\n          request = self.context\n\n          # Extract the preferred language from a cookie:\n          lang = request.cookies.get('language', 'en')\n\n          # According to IUserPreferredLanguages, we must return a list.\n          return [lang]\n\nMulti-adapter\n-------------\n\nHere's a multi-adapter that functions as a content provider as known\nfrom the ``zope.contentprovider`` library.  Content providers are\ncomponents that return snippets of HTML.  They're multi-adapters for\nthe content object (model), the request and the view that they're\nsupposed to be a part of::\n\n  import grokcore.component\n  from zope.publisher.interfaces.browser import IBrowserRequest\n  from zope.publisher.interfaces.browser import IBrowserPage\n  from zope.contentprovider.interfaces import IContentProvider\n\n  class HelloWorldProvider(grokcore.component.MultiAdapter):\n      \"\"\"Display Hello World!\"\"\"\n      grokcore.component.adapts(Interface, IBrowserRequest, IBrowserPage)\n      grokcore.component.implements(IContentProvider)\n\n      def __init__(self, context, request, view):\n          pass\n\n      def update(self):\n          pass\n\n      def render(self):\n          return u'\u003cp\u003eHello World!\u003c/p\u003e'\n\n\nGlobal utility\n--------------\n\nHere's a simple named utility, again from the Zope world.  It's a\ntranslation domain.  In other words, it contains translations of user\nmessages and is invoked when the i18n machinery needs to translate\nsomething::\n\n  import grokcore.component\n  from zope.i18n.interfaces import ITranslationDomain\n\n  class HelloWorldTranslationDomain(grokcore.component.GlobalUtility):\n      grokcore.component.implements(ITranslationDomain)\n      grokcore.component.name('helloworld')\n\n      domain = u'helloworld'\n\n      def translate(self, msgid, mapping=None, context=None,\n                    target_language=None, default=None):\n          if target_language is None:\n              preferred = IUserPreferredLanguages(context)\n              target_language = preferred.getPreferredLanguages()[0]\n\n          translations = {'de': u'Hallo Welt',\n                          'nl': u'Hallo Wereld'}\n          return translations.get(target_language, u'Hello World')\n\nOf course, it's silly to implement your own translation domain utility\nif there are already implementations available in ``zope.i18n`` (one\nthat reads translations from a GNU gettext message catalog and a\nsimple implementation for tests).  Let's try to reuse that\nimplementation and register an instance::\n\n  import grokcore.component\n  from zope.i18n.interfaces import ITranslationDomain\n  from zope.i18n.simpletranslationdomain import SimpleTranslationDomain\n\n  messages = {('de', u'Hello World'): u'Hallo Welt',\n              ('nl', u'Hello World'): u'Hallo Wereld'}\n  helloworld_domain = SimpleTranslationDomain(u'helloworld', messages)\n\n  grokcore.component.global_utility(helloworld_domain,\n                                    provides=ITranslationDomain,\n                                    name='helloworld',\n                                    direct=True)\n\nGlobal adapter\n--------------\n\nSometimes, you may have an object that should be registered as an adapter\nfactory. It may have come from some other framework that configured that\nadapter for you, say, or you may have a class that you instantiate many\ntimes to get different variations on a particular adapter factory. In these\ncases, subclassing grokcore.component.Adapter or MultiAdapter is not\npossible. Instead, you can use the global_adapter() directive. Here is an\nexample drawing on the ``z3c.form`` library, which provides an adapter factory\nfactory for named widget attributes::\n\n  import zope.interface\n  import zope.schema\n  import grokcore.component\n  import z3c.form.widget import ComputedWidgetAttribute\n\n  class ISchema(Interface):\n      \"\"\"This schema will be used to power a z3c.form form\"\"\"\n\n      field = zope.schema.TextLine(title=u\"Sample field\")\n\n  ...\n\n  label_override = z3c.form.widget.StaticWidgetAttribute(\n                        u\"Override label\", field=ISchema['field'])\n\n  grokcore.component.global_adapter(label_override, name=u\"label\")\n\nIn the example above, the provided and adapted interfaces are deduced from the\nobject returned by the ``StaticWidgetAttribute`` factory. The full syntax\nfor global_adapter is::\n\n  global_adapter(factory, (IAdapted1, IAdapted2,), IProvided, name=u\"name\")\n\nThe factory must be a callable (the adapter factory). Adapted interfaces are\ngiven as a tuple. You may use a single interface instead of a one-element\ntuple for single adapters. The provided interface is given as shown. The name\ndefaults to u\"\" (an unnamed adapter).\n\nHandling events\n---------------\n\nHere we see an event handler much like it occurs within Zope itself. It\nsubscribes to the modified event for all annotatable objects (in other words,\nobjects that can have metadata associated with them). When invoked, it updates\nthe Dublin Core 'Modified' property accordingly::\n\n  import datetime\n  import grokcore.component\n  from zope.annotation.interfaces import IAnnotatable\n  from zope.lifecycleevent.interfaces import IObjectModifiedEvent\n  from zope.dublincore.interfaces import IZopeDublinCore\n\n  @grokcore.component.subscribe(IAnnotatable, IObjectModifiedEvent)\n  def updateDublinCoreAfterModification(obj, event):\n      \"\"\"Updated the Dublin Core 'Modified' property when a modified\n      event is sent for an object.\"\"\"\n      IZopeDublinCore(obj).modified = datetime.datetime.utcnow()\n\nSubscriptions\n-------------\n\nSubscriptions look similar to Adapter, however, unlike regular adapters,\nsubscription adapters are used when we want all of the adapters that adapt an\nobject to a particular adapter.\n\nAnalogous to MultiAdapter, there is a MultiSubscription component that \"adapts\"\nmultiple objects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzopefoundation%2Fgrokcore.component","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzopefoundation%2Fgrokcore.component","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzopefoundation%2Fgrokcore.component/lists"}