{"id":20885814,"url":"https://github.com/compas-dev/compas-actions.ghpython_components","last_synced_at":"2025-04-07T11:04:05.666Z","repository":{"id":50495978,"uuid":"359234559","full_name":"compas-dev/compas-actions.ghpython_components","owner":"compas-dev","description":"Trying to make Grasshopper development version-control friendlier since 1337.","archived":false,"fork":false,"pushed_at":"2025-01-29T16:24:44.000Z","size":250,"stargazers_count":44,"open_issues_count":1,"forks_count":6,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-31T10:08:58.602Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/compas-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-04-18T19:27:32.000Z","updated_at":"2025-03-24T01:49:08.000Z","dependencies_parsed_at":"2024-02-11T11:29:29.763Z","dependency_job_id":"9f4c727e-c907-4055-a9cc-768da11ccd75","html_url":"https://github.com/compas-dev/compas-actions.ghpython_components","commit_stats":{"total_commits":87,"total_committers":5,"mean_commits":17.4,"dds":0.5632183908045977,"last_synced_commit":"dbd0108a070255a7c181c5ea6c14ddce79108cbf"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compas-dev%2Fcompas-actions.ghpython_components","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compas-dev%2Fcompas-actions.ghpython_components/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compas-dev%2Fcompas-actions.ghpython_components/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compas-dev%2Fcompas-actions.ghpython_components/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/compas-dev","download_url":"https://codeload.github.com/compas-dev/compas-actions.ghpython_components/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247640461,"owners_count":20971557,"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-18T08:14:43.549Z","updated_at":"2025-04-07T11:04:05.645Z","avatar_url":"https://github.com/compas-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GHPython Componentizer\n\n\u003e A github action to make Grasshopper development 165% \u003csup\u003e\u003csmall\u003e[1]\u003c/small\u003e\u003c/sup\u003e version-control friendlier and 83% more pleasant.\n\nImagine if you could write your grasshopper components in Python code (both IronPython for RhinoV7 and less, or CPython for RhinoV8) in an actual text file with a powerful editor?\nGit wouldn't hate you and life would be so much beautiful. 🐵\n\nWell, here's an action for you then! 🦸‍♀️\n\n---\n\n## Usage\n\n### Usage from Github Actions\n\nThe recommended way to use this tool is as a Github Action.\nIt needs to be run on a windows runner and IronPython/NuGet or Python3/pythonnet/Nuget depending of which component you want to build, needs to be pre-installed.\n\nCopy the following workflow code into a `.github/workflows/main.yml` file in your repository.\nMake sure you have the components definition (see below for details) stored in a source folder.\nReplace the `source` and `target` to match your folder structure.\nTo specify the interpreter to use, you can define the action parameter `interpreter` to either `ironpython` or `python3` (by default it is `ironpython`).\n\nFor IronPython (RhinoV7 and less):\n\n```yaml\non: [push]\n\njobs:\n  build_ipy_ghuser_components:\n    runs-on: windows-latest\n    steps:\n      - uses: actions/checkout@v2\n      - uses: NuGet/setup-nuget@v1.0.5\n\n      - name: Install IronPython\n        run: |\n          choco install ironpython --version=2.7.8.1\n\n      - uses: compas-dev/compas-actions.ghpython_components@v5\n        with:\n          source: components\n          target: build\n\n      # The components have been built at this step.\n      # Now you can choose what to do with them, e.g.:\n      # upload them as artifacts:\n      - uses: actions/upload-artifact@v2\n        with:\n          name: ipy_ghuser-components\n          path: build\n```\n\nFor Python3 (RhinoV8):\n\n```yaml\non: [push]\n\njobs:\n  build_cpy_ghuser_components:\n    runs-on: windows-latest\n    steps:\n      - uses: actions/checkout@v2\n      - uses: NuGet/setup-nuget@v1.0.5\n\n      - name: Install CPython and pythonnet package\n        run: |\n          choco install python --version=3.9.10\n          python -m pip install pythonnet==3.0.3\n\n      - uses: compas-dev/compas-actions.ghpython_components@v5\n        with:\n          source: components\n          target: build\n          interpreter: cpython  # optional, defaults to ironpython\n\n      - uses: actions/upload-artifact@v2\n        with:\n          name: cpy_ghuser-components\n          path: build\n```\n\nFor IronPython2 (RhinoV8):\n\n```yaml\non: [push]\n\njobs:\n  build_ipy_ghuser_components:\n    runs-on: windows-latest\n    steps:\n      - uses: actions/checkout@v2\n      - uses: NuGet/setup-nuget@v1.0.5\n\n      - name: Install IronPython\n        run: |\n          choco install ironpython --version=2.7.8.1\n\n      - uses: compas-dev/compas-actions.ghpython_components@v5\n        with:\n          source: components\n          target: build\n          interpreter: ipy_v2\n\n      # The components have been built at this step.\n      # Now you can choose what to do with them, e.g.:\n      # upload them as artifacts:\n      - uses: actions/upload-artifact@v2\n        with:\n          name: ipy_ghuser-components\n          path: build\n```\n\n\nCommit, push and enjoy! 🍿\n\n### Usage on the command line\n\nAlternatively, you can also use this tool directly from the command line.\nMake sure to have IronPython or Python3/pythonnet installed and the `GH_IO.dll` assembly available.\nThen start the script pointing it to a source and target folder, e.g.:\n\n    ipy componentize_ipy.py examples/ipy build\n    ipy componentize_ipy_v2.py examples/ipy_v2 build\n    python componentize_cpy.py examples/cpy build\n\nOptionally, tag it with a version:\n\n    ipy componentize_ipy.py examples/ipy build --version 0.1.2\n    ipy componentize_ipy_v2.py examples/ipy_v2 build --version 0.1.2\n    python componentize_cpy.py examples/cpy build --version 0.1.2\n\nAn optional name prefix can help tell components apart from other similarly named ones:\n\n    ipy componentize_ipy.py examples/ipy build --prefix \"(PACKAGE-NAME)\"\n    ipy componentize_ipy.py examples/ipy_v2 build --prefix \"(PACKAGE-NAME)\"\n    python componentize_cpy.py examples/cpy build --prefix \"(PACKAGE-NAME)\"\n\n## How to create components\n\n1. Create a folder to contain your components\n1. Each component goes into its own folder\n1. The name of the folder determines the name of the `.ghuser` file created\n1. Inside the component folder:\n   1. Create a `metadata.json` file containing all required details of the component\n   1. Add a lovely icon named `icon.png` (24x24)\n   1. Add a `code.py` file with the Python script of the component\n1. Use this action setting `source` and `target` folder inputs\n1. Be happy 🎈\n\n## Where are the generated components?\n\nThis action stores the generated components under the `target` folder, but these files only exist for the duration of the build.\nAfter that -if no further steps are taken- they will be automatically deleted.\n\nThe simplest option to keep the generated files is to use the `actions/upload-artifact@v2` action and upload them as artifacts. Check [this for more details](https://github.com/actions/upload-artifact) and in particular, [the details about where to find the uploaded artifacts](https://github.com/actions/upload-artifact#where-does-the-upload-go).\n\nAn alternative is to include them in your packaging steps, e.g. calling `python setup.py clean --all sdist bdist_wheel` right after having generated the components (and assuming your setup is configured accordingly, will pick up the components and add them to the pip package. This is a very convenient way that ensures the components are always released from a clean state. An example of this is available on the [release workflow of COMPAS](https://github.com/compas-dev/compas/blob/main/.github/workflows/release.yml).\n\n## Specification\n\n### Icon\n\n* Icon name should be `icon.png`\n* Icon dimensions should be `24x24`\n\n## Python code\n\nSupports a small set of templated variables that can be used in code:\n  * `{{version}}`: Gets replaced with the version, if specified in the command-line.\n  * `{{name}}`: Gets replaced with the name of the component as defined in the metadata file.\n  * `{{ghuser_name}}`: Gets replaced with the name of the `.ghuser` file being generated.\n\n## Metadata\n\n* `name`: Name of the component. Keep it short, single words are best.\n* `nickname`: Abbreviation of the component. Keep it short, 1~5 character words are best.\n* `category`: Category of the component. The category controls in which tab the component will end up.\n* `subcategory`: Subcategory for this component. The subcategory controls in which panel the component will end up.\n* `description`: **(optional)** Description of the component. Be succinct but clear.\n* `exposure`: **(optional)** Controls where the component will be exposed. Defaults to `2` (primary). Accepts one of the following integer values:\n  * `-1`:  Hidden. Do not expose the object anywhere.\n  * `2`: Primary. Expose the object in the first section on the toolbar.\n  * `4`: Secondary. Expose the object in the second section on the toolbar.\n  * `8`: Expose the object in the third section on the toolbar.\n  * `16`: Expose the object in the fourth section on the toolbar.\n  * `32`: Expose the object in the fifth section on the toolbar.\n  * `64`: Expose the object in the sixth section on the toolbar.\n  * `128`: Expose the object in the seventh section on the toolbar.\n* `instanceGuid`: **(optional)** Statically define a GUID for this instance. Defaults to a new Guid.\n* `ghpython`\n  * `hideOutput`: **(optional ⚠️ only IronPython)** Defines whether to hide or not `out` output parameter. Defaults to `True`.\n  * `hideInput`: **(optional ⚠️ only IronPython)** Defines whether to hide or not the `code` input parameter. Defaults to `True`.\n  * `isAdvancedMode`: **(optional ⚠️ only IronPython)** Defines whether the script is in advanced mode (aka GH_Component SDK mode) or procedural mode. Defaults to `False`.\n  * `marshalOutGuids`: **(optional ⚠️ only IronPython)** Defines whether output Guids will be looked up or not. Defaults to `True`. Change to `False` to preserve output Guids.\n  * `marshalGuids`: **(optional ⚠️ only CPython)** Defines whether input Guids will be looked up or not. Defaults to `True`. Change to `False` to preserve input Guids.\n  * `iconDisplay`: **(optional)** Defines whether to display the icon or not. Defaults to `0`.\n    * `0` : Application setting\n    * `1` : Text display\n    * `2` : Icon display\n  * `inputParameters`: List of input parameters.\n    * `name`: Name of the input parameter.\n    * `nickname`: **(optional)** Abbreviation of the input parameter. Defaults to the same as `name`.\n    * `description`: **(optional)** Description of the input parameter.\n    * `optional`: **(optional)** Defines whether the input parameter is optional or not. Defaults to `True`.\n    * `allowTreeAccess`: **(optional)** Defines whether to allow tree access for this input parameter. Defaults to `True`.\n    * `showTypeHints`: **(optional)** Defines whether to show type hints for this input parameter. Defaults to `True`.\n    * `scriptParamAccess`: **(optional)** Defines access type of the parameter. Defaults to `item`. Accepts either integer value or string value.\n      * `0` / `item`: item access\n      * `1` / `list`: list access\n      * `2` / `tree`: tree access\n    * `wireDisplay`: **(optional)** Defines wire display type. Accepts either integer value or string value.\n      * `0` / `default`: Wire display is controlled by the application settings.\n      * `1` / `faint`: Wires are displayed faintly (thin and transparent) while the parameter is not selected.\n      * `2` / `hidden`: Wires are not displayed at all while the parameter is not selected.\n    * `typeHintID`: **(optional)** Defines the type hint of the input parameter. Defaults to `ghdoc`.\n      Accepts either a Guid value or a string value. The following are the valid\n      string values (their respective Guids are not listed here for readability):\n      `none`, `ghdoc`, `float`, `bool`, `int`, `complex`, `str`, `datetime`, `guid`,\n      `color`, `point`, `vector`, `plane`, `interval`, `uvinterval`, `box`, `transform`,\n      `line`, `circle`, `arc`, `polyline`, `rectangle`, `curve`, `mesh`, `surface`, `subd`, `brep`, `pointcloud`, `geometrybase`.\n    * `reverse`: **(optional)** Defines whether data inside the parameter is reversed. Defaults to `False`.\n    * `simplify`: **(optional)** Defines whether data inside the parameter is simplified. Defaults to `False`.\n    * `flatten`: **(optional)** Defines whether data inside the parameter is flattened. Mutually exclusive with `graft`. Defaults to `False`.\n    * `graft`: **(optional)** Defines whether data inside the parameter is grafted. Mutually exclusive with `flatten`. Defaults to `False`.\n  * `outputParameters`: List of output parameters.\n    * `name`: Name of the output parameter.\n    * `nickname`: **(optional)** Abbreviation of the output parameter. Defaults to the same as `name`.\n    * `description`: **(optional)** Description of the output parameter.\n    * `optional`: **(optional)** Defines whether the output parameter is optional or not. Defaults to `False`.\n    * `reverse`: **(optional)** Defines whether data inside the parameter is reversed. Defaults to `False`.\n    * `simplify`: **(optional)** Defines whether data inside the parameter is simplified. Defaults to `False`.\n    * `flatten`: **(optional)** Defines whether data inside the parameter is flattened. Mutually exclusive with `graft`. Defaults to `False`.\n    * `graft`: **(optional)** Defines whether data inside the parameter is grafted. Mutually exclusive with `flatten`. Defaults to `False`.\n\n## Caveats\n\nGHUser components have one important limitation: once used in a document, they forget who they are.\nThe don't know they were created out of a `ghuser` component, they will be simple GHPython components.\nThis has an important consequence: **if you update the `ghuser` components,\nthose already in use will NOT be automatically updated**.\n\n## License\n\nThis package is maintained by Gramazio Kohler Research [@gramaziokohler](https://github.com/gramaziokohler)\nand it is published under an [MIT License](LICENSE).\n\n---\n\u003e \u003csup\u003e[1] Like, totally scientifically proven. word.\u003c/sup\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcompas-dev%2Fcompas-actions.ghpython_components","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcompas-dev%2Fcompas-actions.ghpython_components","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcompas-dev%2Fcompas-actions.ghpython_components/lists"}