{"id":21029853,"url":"https://github.com/kitconcept/kitconcept.solr","last_synced_at":"2025-05-15T11:32:16.094Z","repository":{"id":75201838,"uuid":"430444341","full_name":"kitconcept/kitconcept.solr","owner":"kitconcept","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-04T11:51:44.000Z","size":290,"stargazers_count":2,"open_issues_count":7,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-11T12:11:33.402Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kitconcept.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.GPL","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":"2021-11-21T18:12:44.000Z","updated_at":"2025-04-01T18:10:17.000Z","dependencies_parsed_at":"2025-01-30T11:23:59.028Z","dependency_job_id":"565f3541-0c25-4975-bef8-294e61940b2f","html_url":"https://github.com/kitconcept/kitconcept.solr","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitconcept%2Fkitconcept.solr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitconcept%2Fkitconcept.solr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitconcept%2Fkitconcept.solr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitconcept%2Fkitconcept.solr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kitconcept","download_url":"https://codeload.github.com/kitconcept/kitconcept.solr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254330799,"owners_count":22053050,"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","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":[],"created_at":"2024-11-19T12:14:32.384Z","updated_at":"2025-05-15T11:32:11.492Z","avatar_url":"https://github.com/kitconcept.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"kitconcept GmbH\" width=\"200px\" src=\"https://kitconcept.com/logo.svg\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ekitconcept.solr\u003c/h1\u003e\n\u003ch3 align=\"center\"\u003eAn opinionated Solr integration for Plone\u003c/h3\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![PyPI](https://img.shields.io/pypi/v/kitconcept.solr)](https://pypi.org/project/kitconcept.solr/)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/kitconcept.solr)](https://pypi.org/project/kitconcept.solr/)\n[![PyPI - Wheel](https://img.shields.io/pypi/wheel/kitconcept.solr)](https://pypi.org/project/kitconcept.solr/)\n[![PyPI - License](https://img.shields.io/pypi/l/kitconcept.solr)](https://pypi.org/project/kitconcept.solr/)\n[![PyPI - Status](https://img.shields.io/pypi/status/kitconcept.solr)](https://pypi.org/project/kitconcept.solr/)\n\n[![PyPI - Plone Versions](https://img.shields.io/pypi/frameworkversions/plone/kitconcept.solr)](https://pypi.org/project/kitconcept.solr/)\n\n[![Meta](https://github.com/kitconcept/kitconcept.solr/actions/workflows/meta.yml/badge.svg)](https://github.com/kitconcept/kitconcept.solr/actions/workflows/meta.yml)\n![Code Style](https://img.shields.io/badge/Code%20Style-Black-000000)\n\n[![GitHub contributors](https://img.shields.io/github/contributors/kitconcept/kitconcept.solr)](https://github.com/kitconcept/kitconcept.solr)\n[![GitHub Repo stars](https://img.shields.io/github/stars/kitconcept/kitconcept.solr?style=social)](https://github.com/kitconcept/kitconcept.solr)\n\n\u003c/div\u003e\n\n## Features\n\n`kitconcept.solr` is an opinionated Solr integration package for Plone sites. It leverages (and depends on) [`collective.solr`](https://github.com/collective/collective.solr), by adding a new endpoint `@solr` that supports search requests with facetted results.\n\n### Endpoints\n\n| name    | context                         |\n| ------- | ------------------------------- |\n| `@solr` | Plone site or Folderish content |\n\n#### Using the `@solr` endpoint\n\nThe `@solr` endpoint is used from the `kitconcept.volto-solr` Volto add-on package for the implementation of the site search. It can also be used for custom components. The parameters roughly follow the parameters of the normal site search service, but differ in some respects.\n\n**TBD** _give more information about this._\n\nFor now, please refer to the source code of the `solr.py` module, in case you want to use for your own purposes.\n\n## Documentation\n\n### Installation\n\nAdd `kitconcept.solr` as a dependency on your package's `setup.py`\n\n```python\n    install_requires = [\n        \"kitconcept.solr\",\n        \"Plone\",\n        \"plone.restapi\",\n        \"setuptools\",\n    ],\n```\n\nAlso, add `kitconcept.solr` to your package's `configure.zcml` (or `dependencies.zcml`):\n\n```xml\n\u003cinclude package=\"kitconcept.solr\" /\u003e\n```\n\n#### Remark with Plone 6.0\n\nWith Plone 6.0 you must add an additional dependency `\"plone.restapi\u003e=8.40.0\"`.\n\nThe package also keeps support with Plone 5.2 where `\"plone.restapi\u003e=8.21.2\"` is a working version. It will not support image scales, but the package will work gracefully without displaying image previews in the search result list.\n\n### Generic Setup\n\nTo automatically enable this package when your add-on is installed, add the following line inside the package's `profiles/default/metadata.xml` `dependencies` element:\n\n```xml\n    \u003cdependency\u003eprofile-kitconcept.solr:default\u003c/dependency\u003e\n```\n\n## Source Code and Contributions\n\nWe welcome contributions to `kitconcept.solr`.\n\nYou can create an issue in the issue tracker, or contact a maintainer.\n\n- [Issue Tracker](https://github.com/kitconcept/kitconcept.solr/issues)\n- [Source Code](https://github.com/kitconcept/kitconcept.solr/)\n\n### Development requirements\n\n- Python 3.8 or later\n- Docker\n\n### Setup\n\nInstall all development dependencies -- including Plone -- and create a new instance using:\n\n```bash\nmake install\n```\n\nBy default, we use the latest Plone version in the 6.x series.\n\n### Configurations\n\nMost of the development configuration is managed with [`plone.meta`](https://github.com/plone/plone.meta), so avoid manually editing the following files:\n\n- `.editorconfig`\n- `.flake8`\n- `.gitignore`\n- `.pre-commit-config.yaml`\n- `news/.changelog_template.jinja`\n- `pyproject.toml`\n- `tox.ini`\n\nIn addition there is Solr related configuration that is outlined in the following chapters.\n\n#### Configuring Solr\n\nSolr is configured by a default configuration that can be found in the [`/solr/etc/`](./solr/etc) folder in this repository. This contains, most notably, the `schema.xml` that defines the indexes for Solr. This package also builds docker images with the default Solr version, set up with this default configuration.\n\nIf you need to customize the Solr configuration (such as adding new indexes, etc.) then you should copy the `solr` folder into your own project, customize it as you wish, and then build your own docker images (or compile your own Solr server) based on this configuration.\n\nA typical use case for why you would want to do this, is if you add new fields to some content types, and you want to render the values for these additional fields in the search results. In this case you want to add the additional fields as indexes to Solr. You probably would not need this, unless you change anything on the result type templates in the `kitconcept.volto-solr` front-end package.\n\n#### Configuring the front-end and back-end packages\n\nThe package supports the usage of the `kitconcept.volto-solr` add-on, and it is designed to be used together with it.\n\nThe configuration can be specified in a customized way. Without any additional configuration, the package will use the default, which is specified in json format in the [`kitconcept.solr.interfaces.IKitconceptSolrSettings`](./src/kitconcept/solr/profiles/default/registry/kitconcept.solr.interfaces.IKitconceptSolrSettings.xml) registry.\n\nThis configuration settings affect the behavior of both the `kitconcept.solr` (this) back-end package, and the `kitconcept.volto-solr` front-end package (a Volto add-on). In addition, `kitconcept.volto-solr` has its own Volto add-on configuration which is not explained here, for these options please refer to the documentation of the add-on package.\n\n##### Configuration options\n\nExplanation for the configuration options:\n\n###### `fieldList`\n\nContains the fields that solr should return. If the search result templates in the volto add-on are modified, and require more fields than in the default list, the fields **must explicitly be added** here.\n\nIn addition, the same fields must be present in the Solr index - if either the Solr index or the field in `fieldList` is missing, the field value will silently be not returned. No error will be shown.\n\nExample value:\n\n```json\n[\n  \"UID\",\n  \"Title\",\n  \"Description\",\n  \"Type\",\n  \"effective\",\n  \"start\",\n  \"created\",\n  \"end\",\n  \"path_string\",\n  \"mime_type\",\n  \"phone\",\n  \"email\",\n  \"location\",\n  \"image_scales\",\n  \"image_field\"\n]\n```\n\n###### `searchTabs`\n\nA list of dictionary items representing the facet tabs in the search page.\n\nThe `label` field specifies the label to be shown on the tab in English. It's the front-end package's responsibility to provide translations for this, as `kitconcept.volto-solr` does this for the defaults, which can be used as an example.\n\nThe `filter` field defines the Solr search condition to the given facet tab. This can be a content type, or in fact any condition understood by Solr, please consult the Solr documentation for more details.\n\nExample value:\n\n```json\n[\n  {\n    \"label\": \"All\",\n    \"filter\": \"Type(*)\"\n  },\n  {\n    \"label\": \"Pages\",\n    \"filter\": \"Type:(Page)\"\n  },\n  {\n    \"label\": \"Events\",\n    \"filter\": \"Type:(Event)\"\n  },\n  {\n    \"label\": \"Images\",\n    \"filter\": \"Type:(Image)\"\n  },\n  {\n    \"label\": \"Files\",\n    \"filter\": \"Type:(File)\"\n  }\n]\n```\n\n##### Overriding the configuration options\n\nIf needed, the default [`kitconcept.solr.interfaces.IKitconceptSolrSettings`](./src/kitconcept/solr/profiles/default/registry/kitconcept.solr.interfaces.IKitconceptSolrSettings.xml) can be customized in the registry via GenericSetup.\n\n### Using reindex helpers\n\nHelpers for activate and reindex solr are importable from the package.\n\nExample for a reindex script that can be called from Makefile:\n\n```py\nfrom kitconcept.solr.reindex_helpers import activate_and_reindex\nfrom Testing.makerequest import makerequest\nfrom zope.site.hooks import setSite\n\nimport sys\nimport transaction\n\n\nif __name__ == \"__main__\":\n    app = makerequest(app)  # noQA\n\n    # Set site to Plone\n    site_id = \"Plone\"\n    portal = app.unrestrictedTraverse(site_id)\n    setSite(portal)\n\n    activate_and_reindex(portal, clear=\"--clear\" in sys.argv)\n\n    transaction.commit()\n    app._p_jar.sync()\n```\n\nExample for an upgrade step that adds the `kitconcept.solr` package, and one that does the solr activation for the first time:\n\n```py\nfrom kitconcept.solr.reindex_helpers import activate_and_reindex\nfrom plone import api\n\nimport logging\n\n\nlogger = logging.getLogger(\"your_package_name_here\")\n\n\n# We suggest to add two distinct upgrade step for the package installation\n# and the solr activation, in case of a failure this allows to\n# identify the problem easier.\n\n\ndef install_kitconcept_solr(context):\n    st = api.portal.get_tool(\"portal_setup\")\n    st.runAllImportStepsFromProfile(\"kitconcept.solr:default\")\n    logger.info(\"Installed kitconcept.solr\")\n\n\ndef activate_and_reindex_solr(context):\n    activate_and_reindex(context)\n    logger.info(\"Activated and reindexed solr\")\n```\n\n### Update translations\n\n```bash\nmake i18n\n```\n\n### Format codebase\n\n```bash\nmake format\n```\n\n### Run tests\n\nTesting of this package is done with [`pytest`](https://docs.pytest.org/) and [`tox`](https://tox.wiki/).\n\nRun all tests with:\n\n```bash\nmake test\n```\n\nRun all tests but stop on the first error and open a `pdb` session:\n\n```bash\n./bin/tox -e test -- -x --pdb\n```\n\nRun only tests that match `TestEndpointEncoding`:\n\n```bash\n./bin/tox -e test -- -k TestEndpointEncoding\n```\n\nRun only tests that match `TestEndpointEncoding`, but stop on the first error and open a `pdb` session:\n\n```bash\n./bin/tox -e test -- -k TestEndpointEncoding -x --pdb\n```\n\n## Credits\n\nThe development of this add-on has been kindly sponsored by [German Aerospace Center (DLR)](https://www.dlr.de) and [Forschungszentrum Jülich](https://www.fz-juelich.de).\n\n\u003cimg alt=\"German Aerospace Center (DLR)\" width=\"200px\" src=\"https://raw.githubusercontent.com/kitconcept/kitconcept.solr/main/docs/dlr.svg\" style=\"background-color:white\"\u003e\n\u003cimg alt=\"Forschungszentrum Jülich\" width=\"200px\" src=\"https://raw.githubusercontent.com/kitconcept/kitconcept.solr/main/docs/fz-juelich.svg\" style=\"background-color:white\"\u003e\n\nDeveloped by [kitconcept](https://www.kitconcept.com/)\n\n## License\n\nThe project is licensed under GPLv2.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitconcept%2Fkitconcept.solr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitconcept%2Fkitconcept.solr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitconcept%2Fkitconcept.solr/lists"}