├── .editorconfig
├── .gitignore
├── .pre-commit-config.yaml
├── .python-version
├── CHANGELOG.md
├── LICENSE
├── LICENSE_header.txt
├── README.md
├── bpy_jupyter
├── __init__.py
├── operators
│ ├── __init__.py
│ ├── copy_kern_info_to_clipboard.py
│ ├── start_jupyter_kernel.py
│ └── stop_jupyter_kernel.py
├── panels
│ ├── __init__.py
│ └── jupyter_panel.py
├── preferences.py
├── services
│ ├── __init__.py
│ ├── async_event_loop.py
│ ├── jupyter_kernel.py
│ └── registration.py
├── types.py
└── utils
│ ├── __init__.py
│ └── ipykernel.py
├── docs
├── index.md
├── installation.md
├── reference
│ ├── contributing.md
│ ├── policies
│ │ ├── licensing.md
│ │ └── versioning.md
│ ├── python_api
│ │ ├── bpy_jupyter.md
│ │ ├── bpy_jupyter_operators.md
│ │ ├── bpy_jupyter_panels.md
│ │ ├── bpy_jupyter_services.md
│ │ └── bpy_jupyter_utils.md
│ └── release_notes.md
└── user_guides
│ ├── getting_started.md
│ └── images
│ ├── panel_active.png
│ ├── panel_default.png
│ └── panel_offline.png
├── mkdocs.yml
├── pyproject.toml
└── uv.lock
/.editorconfig:
--------------------------------------------------------------------------------
1 | [*]
2 | end_of_line = lf
3 | insert_final_newline = true
4 | charset = utf-8
5 |
6 | indent_style = tab
7 | indent_size = 4
8 | trim_trailing_whitespace = false
9 |
10 | [*.yml]
11 | indent_style = space
12 | indent_size = 2
13 |
14 | [*.yaml]
15 | indent_style = space
16 | indent_size = 2
17 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .blext_cache
2 |
3 | # Byte-compiled / optimized / DLL files
4 | .dev
5 | __pycache__/
6 | *.py[cod]
7 | *$py.class
8 |
9 | # C extensions
10 | *.so
11 |
12 | # Distribution / packaging
13 | .Python
14 | build/
15 | develop-eggs/
16 | dist/
17 | downloads/
18 | eggs/
19 | .eggs/
20 | lib/
21 | lib64/
22 | parts/
23 | sdist/
24 | var/
25 | wheels/
26 | share/python-wheels/
27 | *.egg-info/
28 | .installed.cfg
29 | *.egg
30 | MANIFEST
31 |
32 | # PyInstaller
33 | # Usually these files are written by a python script from a template
34 | # before PyInstaller builds the exe, so as to inject date/other infos into it.
35 | *.manifest
36 | *.spec
37 |
38 | # Installer logs
39 | pip-log.txt
40 | pip-delete-this-directory.txt
41 |
42 | # Unit test / coverage reports
43 | htmlcov/
44 | .tox/
45 | .nox/
46 | .coverage
47 | .coverage.*
48 | .cache
49 | nosetests.xml
50 | coverage.xml
51 | *.cover
52 | *.py,cover
53 | .hypothesis/
54 | .pytest_cache/
55 | cover/
56 |
57 | # Translations
58 | *.mo
59 | *.pot
60 |
61 | # Django stuff:
62 | *.log
63 | local_settings.py
64 | db.sqlite3
65 | db.sqlite3-journal
66 |
67 | # Flask stuff:
68 | instance/
69 | .webassets-cache
70 |
71 | # Scrapy stuff:
72 | .scrapy
73 |
74 | # Sphinx documentation
75 | docs/_build/
76 |
77 | # PyBuilder
78 | .pybuilder/
79 | target/
80 |
81 | # Jupyter Notebook
82 | .ipynb_checkpoints
83 |
84 | # IPython
85 | profile_default/
86 | ipython_config.py
87 |
88 | # pyenv
89 | # For a library or package, you might want to ignore these files since the code is
90 | # intended to run in multiple environments; otherwise, check them in:
91 | # .python-version
92 |
93 | # pipenv
94 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
95 | # However, in case of collaboration, if having platform-specific dependencies or dependencies
96 | # having no cross-platform support, pipenv may install dependencies that don't work, or not
97 | # install all needed dependencies.
98 | #Pipfile.lock
99 |
100 | # poetry
101 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
102 | # This is especially recommended for binary packages to ensure reproducibility, and is more
103 | # commonly ignored for libraries.
104 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
105 | #poetry.lock
106 |
107 | # pdm
108 | # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
109 | #pdm.lock
110 | # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
111 | # in version control.
112 | # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
113 | .pdm.toml
114 | .pdm-python
115 | .pdm-build/
116 |
117 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
118 | __pypackages__/
119 |
120 | # Celery stuff
121 | celerybeat-schedule
122 | celerybeat.pid
123 |
124 | # SageMath parsed files
125 | *.sage.py
126 |
127 | # Environments
128 | .env
129 | .venv
130 | env/
131 | venv/
132 | ENV/
133 | env.bak/
134 | venv.bak/
135 |
136 | # Spyder project settings
137 | .spyderproject
138 | .spyproject
139 |
140 | # Rope project settings
141 | .ropeproject
142 |
143 | # mkdocs documentation
144 | /site
145 |
146 | # mypy
147 | .mypy_cache/
148 | .dmypy.json
149 | dmypy.json
150 |
151 | # Pyre type checker
152 | .pyre/
153 |
154 | # pytype static type analyzer
155 | .pytype/
156 |
157 | # Cython debug symbols
158 | cython_debug/
159 |
160 | # PyCharm
161 | # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
162 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
163 | # and can be added to the global gitignore or merged into this file. For a more nuclear
164 | # option (not recommended) you can uncomment the following to ignore the entire idea folder.
165 | #.idea/
166 |
--------------------------------------------------------------------------------
/.pre-commit-config.yaml:
--------------------------------------------------------------------------------
1 | # See https://pre-commit.com for more information
2 | # See https://pre-commit.com/hooks.html for more hooks
3 | repos:
4 | - repo: https://github.com/Lucas-C/pre-commit-hooks
5 | rev: v1.5.5
6 | hooks:
7 | - id: forbid-crlf
8 | - id: remove-crlf
9 | - id: chmod
10 | args: ['644']
11 | files: \.md$
12 | - id: insert-license
13 | files: \.py$
14 | args:
15 | - --license-filepath
16 | - LICENSE_header.txt
17 | - --comment-style
18 | - "#"
19 | - --use-current-year
20 | - --fuzzy-match-generates-todo
21 |
22 | - repo: https://github.com/astral-sh/ruff-pre-commit
23 | # Ruff version.
24 | rev: v0.11.8
25 | hooks:
26 | # ruff lint
27 | - id: ruff
28 | # ruff fmt
29 | - id: ruff-format
30 |
31 | - repo: https://github.com/DetachHead/basedpyright-pre-commit-mirror
32 | rev: 1.29.1
33 | hooks:
34 | - id: basedpyright
35 |
36 | - repo: https://github.com/commitizen-tools/commitizen
37 | rev: v4.1.0
38 | hooks:
39 | - id: commitizen
40 | additional_dependencies: [cz-conventional-gitmoji]
41 | - id: commitizen-branch
42 | stages: [push]
43 |
--------------------------------------------------------------------------------
/.python-version:
--------------------------------------------------------------------------------
1 | 3.11
2 |
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | ## v0.3.0 (2025-05-06)
2 |
3 | ### ✨ Features
4 |
5 | - comprehensive new UI
6 | - polished up with last fixes, docs, and tooling
7 |
8 | ### 🐛🚑️ Fixes
9 |
10 | - don't start `asyncio` event loop when `bpy.app.online_access` is disabled
11 | - respect `bpy.app.online_access`
12 |
13 | ### BREAKING CHANGE
14 |
15 | - Users can no longer rely on `anywidget` by default.
16 | - Use of the extension now requires enabling `bpy.app.online_access`.
17 | - The extension no longer provides a web service. Please use the kernel connection file directly, or with an externally defined web service.
18 |
19 | ### chore
20 |
21 | - License headers, lightweight pre-commit hooks.
22 | - ruff formatting
23 |
24 | ### docs
25 |
26 | - added a lot of documentation and switched to `fake-bpy-module`
27 | - Made a README!
28 |
29 | ### feat
30 |
31 | - banish the web server
32 | - switch to latest `blext` main
33 | - New "Copy URL" button in revamped UI
34 | - UI panel settings.
35 | - External blext and Stop Kernel panel
36 | - Working jupyter kernel bridge!
37 | - Almost working - blext is nice now, however.
38 | - Nonworking post-BCon24 extension!
39 |
40 | ### fix
41 |
42 | - fixed kernel environment state being preserved between stop/start
43 | - fixed flush before `self._kernel_app.close()`
44 | - we can stop the kernel now, but removing `print()` breaks `stdout`
45 | - fix bad imports and prune project spec
46 | - updated `blext` to fix build
47 | - new `blext` version to fix large `.zip`s, other problems
48 | - Import typo, default `root-dir` to `Desktop/`
49 | - Clean stop of IPKernelApp
50 | - Added macos9 universal2 requirement
51 | - Added macos15 universal requirement
52 | - Added macos15 support
53 | - Conform macos platform name to Blender.
54 | - Better platform-specific blender executable detection.
55 | - Launch Blender subprocess properly.
56 |
57 | ### refactor
58 |
59 | - general refactor w/correct dependencies
60 |
61 | ### 📌➕⬇️➖⬆️ Dependencies
62 |
63 | - remove dependency on `anywidget`
64 |
65 | ### 📝💡 Documentation
66 |
67 | - polished documentation up for deployment
68 | - wrote a lot of documentation
69 | - updated some docs and release information
70 | - fixed name of `bl_classes` in docstring
71 | - initialized `mkdocs` documentation site
72 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | GNU AFFERO GENERAL PUBLIC LICENSE
2 | Version 3, 19 November 2007
3 |
4 | Copyright (C) 2007 Free Software Foundation, Inc.
5 | Everyone is permitted to copy and distribute verbatim copies
6 | of this license document, but changing it is not allowed.
7 |
8 | Preamble
9 |
10 | The GNU Affero General Public License is a free, copyleft license for
11 | software and other kinds of works, specifically designed to ensure
12 | cooperation with the community in the case of network server software.
13 |
14 | The licenses for most software and other practical works are designed
15 | to take away your freedom to share and change the works. By contrast,
16 | our General Public Licenses are intended to guarantee your freedom to
17 | share and change all versions of a program--to make sure it remains free
18 | software for all its users.
19 |
20 | When we speak of free software, we are referring to freedom, not
21 | price. Our General Public Licenses are designed to make sure that you
22 | have the freedom to distribute copies of free software (and charge for
23 | them if you wish), that you receive source code or can get it if you
24 | want it, that you can change the software or use pieces of it in new
25 | free programs, and that you know you can do these things.
26 |
27 | Developers that use our General Public Licenses protect your rights
28 | with two steps: (1) assert copyright on the software, and (2) offer
29 | you this License which gives you legal permission to copy, distribute
30 | and/or modify the software.
31 |
32 | A secondary benefit of defending all users' freedom is that
33 | improvements made in alternate versions of the program, if they
34 | receive widespread use, become available for other developers to
35 | incorporate. Many developers of free software are heartened and
36 | encouraged by the resulting cooperation. However, in the case of
37 | software used on network servers, this result may fail to come about.
38 | The GNU General Public License permits making a modified version and
39 | letting the public access it on a server without ever releasing its
40 | source code to the public.
41 |
42 | The GNU Affero General Public License is designed specifically to
43 | ensure that, in such cases, the modified source code becomes available
44 | to the community. It requires the operator of a network server to
45 | provide the source code of the modified version running there to the
46 | users of that server. Therefore, public use of a modified version, on
47 | a publicly accessible server, gives the public access to the source
48 | code of the modified version.
49 |
50 | An older license, called the Affero General Public License and
51 | published by Affero, was designed to accomplish similar goals. This is
52 | a different license, not a version of the Affero GPL, but Affero has
53 | released a new version of the Affero GPL which permits relicensing under
54 | this license.
55 |
56 | The precise terms and conditions for copying, distribution and
57 | modification follow.
58 |
59 | TERMS AND CONDITIONS
60 |
61 | 0. Definitions.
62 |
63 | "This License" refers to version 3 of the GNU Affero General Public License.
64 |
65 | "Copyright" also means copyright-like laws that apply to other kinds of
66 | works, such as semiconductor masks.
67 |
68 | "The Program" refers to any copyrightable work licensed under this
69 | License. Each licensee is addressed as "you". "Licensees" and
70 | "recipients" may be individuals or organizations.
71 |
72 | To "modify" a work means to copy from or adapt all or part of the work
73 | in a fashion requiring copyright permission, other than the making of an
74 | exact copy. The resulting work is called a "modified version" of the
75 | earlier work or a work "based on" the earlier work.
76 |
77 | A "covered work" means either the unmodified Program or a work based
78 | on the Program.
79 |
80 | To "propagate" a work means to do anything with it that, without
81 | permission, would make you directly or secondarily liable for
82 | infringement under applicable copyright law, except executing it on a
83 | computer or modifying a private copy. Propagation includes copying,
84 | distribution (with or without modification), making available to the
85 | public, and in some countries other activities as well.
86 |
87 | To "convey" a work means any kind of propagation that enables other
88 | parties to make or receive copies. Mere interaction with a user through
89 | a computer network, with no transfer of a copy, is not conveying.
90 |
91 | An interactive user interface displays "Appropriate Legal Notices"
92 | to the extent that it includes a convenient and prominently visible
93 | feature that (1) displays an appropriate copyright notice, and (2)
94 | tells the user that there is no warranty for the work (except to the
95 | extent that warranties are provided), that licensees may convey the
96 | work under this License, and how to view a copy of this License. If
97 | the interface presents a list of user commands or options, such as a
98 | menu, a prominent item in the list meets this criterion.
99 |
100 | 1. Source Code.
101 |
102 | The "source code" for a work means the preferred form of the work
103 | for making modifications to it. "Object code" means any non-source
104 | form of a work.
105 |
106 | A "Standard Interface" means an interface that either is an official
107 | standard defined by a recognized standards body, or, in the case of
108 | interfaces specified for a particular programming language, one that
109 | is widely used among developers working in that language.
110 |
111 | The "System Libraries" of an executable work include anything, other
112 | than the work as a whole, that (a) is included in the normal form of
113 | packaging a Major Component, but which is not part of that Major
114 | Component, and (b) serves only to enable use of the work with that
115 | Major Component, or to implement a Standard Interface for which an
116 | implementation is available to the public in source code form. A
117 | "Major Component", in this context, means a major essential component
118 | (kernel, window system, and so on) of the specific operating system
119 | (if any) on which the executable work runs, or a compiler used to
120 | produce the work, or an object code interpreter used to run it.
121 |
122 | The "Corresponding Source" for a work in object code form means all
123 | the source code needed to generate, install, and (for an executable
124 | work) run the object code and to modify the work, including scripts to
125 | control those activities. However, it does not include the work's
126 | System Libraries, or general-purpose tools or generally available free
127 | programs which are used unmodified in performing those activities but
128 | which are not part of the work. For example, Corresponding Source
129 | includes interface definition files associated with source files for
130 | the work, and the source code for shared libraries and dynamically
131 | linked subprograms that the work is specifically designed to require,
132 | such as by intimate data communication or control flow between those
133 | subprograms and other parts of the work.
134 |
135 | The Corresponding Source need not include anything that users
136 | can regenerate automatically from other parts of the Corresponding
137 | Source.
138 |
139 | The Corresponding Source for a work in source code form is that
140 | same work.
141 |
142 | 2. Basic Permissions.
143 |
144 | All rights granted under this License are granted for the term of
145 | copyright on the Program, and are irrevocable provided the stated
146 | conditions are met. This License explicitly affirms your unlimited
147 | permission to run the unmodified Program. The output from running a
148 | covered work is covered by this License only if the output, given its
149 | content, constitutes a covered work. This License acknowledges your
150 | rights of fair use or other equivalent, as provided by copyright law.
151 |
152 | You may make, run and propagate covered works that you do not
153 | convey, without conditions so long as your license otherwise remains
154 | in force. You may convey covered works to others for the sole purpose
155 | of having them make modifications exclusively for you, or provide you
156 | with facilities for running those works, provided that you comply with
157 | the terms of this License in conveying all material for which you do
158 | not control copyright. Those thus making or running the covered works
159 | for you must do so exclusively on your behalf, under your direction
160 | and control, on terms that prohibit them from making any copies of
161 | your copyrighted material outside their relationship with you.
162 |
163 | Conveying under any other circumstances is permitted solely under
164 | the conditions stated below. Sublicensing is not allowed; section 10
165 | makes it unnecessary.
166 |
167 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
168 |
169 | No covered work shall be deemed part of an effective technological
170 | measure under any applicable law fulfilling obligations under article
171 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or
172 | similar laws prohibiting or restricting circumvention of such
173 | measures.
174 |
175 | When you convey a covered work, you waive any legal power to forbid
176 | circumvention of technological measures to the extent such circumvention
177 | is effected by exercising rights under this License with respect to
178 | the covered work, and you disclaim any intention to limit operation or
179 | modification of the work as a means of enforcing, against the work's
180 | users, your or third parties' legal rights to forbid circumvention of
181 | technological measures.
182 |
183 | 4. Conveying Verbatim Copies.
184 |
185 | You may convey verbatim copies of the Program's source code as you
186 | receive it, in any medium, provided that you conspicuously and
187 | appropriately publish on each copy an appropriate copyright notice;
188 | keep intact all notices stating that this License and any
189 | non-permissive terms added in accord with section 7 apply to the code;
190 | keep intact all notices of the absence of any warranty; and give all
191 | recipients a copy of this License along with the Program.
192 |
193 | You may charge any price or no price for each copy that you convey,
194 | and you may offer support or warranty protection for a fee.
195 |
196 | 5. Conveying Modified Source Versions.
197 |
198 | You may convey a work based on the Program, or the modifications to
199 | produce it from the Program, in the form of source code under the
200 | terms of section 4, provided that you also meet all of these conditions:
201 |
202 | a) The work must carry prominent notices stating that you modified
203 | it, and giving a relevant date.
204 |
205 | b) The work must carry prominent notices stating that it is
206 | released under this License and any conditions added under section
207 | 7. This requirement modifies the requirement in section 4 to
208 | "keep intact all notices".
209 |
210 | c) You must license the entire work, as a whole, under this
211 | License to anyone who comes into possession of a copy. This
212 | License will therefore apply, along with any applicable section 7
213 | additional terms, to the whole of the work, and all its parts,
214 | regardless of how they are packaged. This License gives no
215 | permission to license the work in any other way, but it does not
216 | invalidate such permission if you have separately received it.
217 |
218 | d) If the work has interactive user interfaces, each must display
219 | Appropriate Legal Notices; however, if the Program has interactive
220 | interfaces that do not display Appropriate Legal Notices, your
221 | work need not make them do so.
222 |
223 | A compilation of a covered work with other separate and independent
224 | works, which are not by their nature extensions of the covered work,
225 | and which are not combined with it such as to form a larger program,
226 | in or on a volume of a storage or distribution medium, is called an
227 | "aggregate" if the compilation and its resulting copyright are not
228 | used to limit the access or legal rights of the compilation's users
229 | beyond what the individual works permit. Inclusion of a covered work
230 | in an aggregate does not cause this License to apply to the other
231 | parts of the aggregate.
232 |
233 | 6. Conveying Non-Source Forms.
234 |
235 | You may convey a covered work in object code form under the terms
236 | of sections 4 and 5, provided that you also convey the
237 | machine-readable Corresponding Source under the terms of this License,
238 | in one of these ways:
239 |
240 | a) Convey the object code in, or embodied in, a physical product
241 | (including a physical distribution medium), accompanied by the
242 | Corresponding Source fixed on a durable physical medium
243 | customarily used for software interchange.
244 |
245 | b) Convey the object code in, or embodied in, a physical product
246 | (including a physical distribution medium), accompanied by a
247 | written offer, valid for at least three years and valid for as
248 | long as you offer spare parts or customer support for that product
249 | model, to give anyone who possesses the object code either (1) a
250 | copy of the Corresponding Source for all the software in the
251 | product that is covered by this License, on a durable physical
252 | medium customarily used for software interchange, for a price no
253 | more than your reasonable cost of physically performing this
254 | conveying of source, or (2) access to copy the
255 | Corresponding Source from a network server at no charge.
256 |
257 | c) Convey individual copies of the object code with a copy of the
258 | written offer to provide the Corresponding Source. This
259 | alternative is allowed only occasionally and noncommercially, and
260 | only if you received the object code with such an offer, in accord
261 | with subsection 6b.
262 |
263 | d) Convey the object code by offering access from a designated
264 | place (gratis or for a charge), and offer equivalent access to the
265 | Corresponding Source in the same way through the same place at no
266 | further charge. You need not require recipients to copy the
267 | Corresponding Source along with the object code. If the place to
268 | copy the object code is a network server, the Corresponding Source
269 | may be on a different server (operated by you or a third party)
270 | that supports equivalent copying facilities, provided you maintain
271 | clear directions next to the object code saying where to find the
272 | Corresponding Source. Regardless of what server hosts the
273 | Corresponding Source, you remain obligated to ensure that it is
274 | available for as long as needed to satisfy these requirements.
275 |
276 | e) Convey the object code using peer-to-peer transmission, provided
277 | you inform other peers where the object code and Corresponding
278 | Source of the work are being offered to the general public at no
279 | charge under subsection 6d.
280 |
281 | A separable portion of the object code, whose source code is excluded
282 | from the Corresponding Source as a System Library, need not be
283 | included in conveying the object code work.
284 |
285 | A "User Product" is either (1) a "consumer product", which means any
286 | tangible personal property which is normally used for personal, family,
287 | or household purposes, or (2) anything designed or sold for incorporation
288 | into a dwelling. In determining whether a product is a consumer product,
289 | doubtful cases shall be resolved in favor of coverage. For a particular
290 | product received by a particular user, "normally used" refers to a
291 | typical or common use of that class of product, regardless of the status
292 | of the particular user or of the way in which the particular user
293 | actually uses, or expects or is expected to use, the product. A product
294 | is a consumer product regardless of whether the product has substantial
295 | commercial, industrial or non-consumer uses, unless such uses represent
296 | the only significant mode of use of the product.
297 |
298 | "Installation Information" for a User Product means any methods,
299 | procedures, authorization keys, or other information required to install
300 | and execute modified versions of a covered work in that User Product from
301 | a modified version of its Corresponding Source. The information must
302 | suffice to ensure that the continued functioning of the modified object
303 | code is in no case prevented or interfered with solely because
304 | modification has been made.
305 |
306 | If you convey an object code work under this section in, or with, or
307 | specifically for use in, a User Product, and the conveying occurs as
308 | part of a transaction in which the right of possession and use of the
309 | User Product is transferred to the recipient in perpetuity or for a
310 | fixed term (regardless of how the transaction is characterized), the
311 | Corresponding Source conveyed under this section must be accompanied
312 | by the Installation Information. But this requirement does not apply
313 | if neither you nor any third party retains the ability to install
314 | modified object code on the User Product (for example, the work has
315 | been installed in ROM).
316 |
317 | The requirement to provide Installation Information does not include a
318 | requirement to continue to provide support service, warranty, or updates
319 | for a work that has been modified or installed by the recipient, or for
320 | the User Product in which it has been modified or installed. Access to a
321 | network may be denied when the modification itself materially and
322 | adversely affects the operation of the network or violates the rules and
323 | protocols for communication across the network.
324 |
325 | Corresponding Source conveyed, and Installation Information provided,
326 | in accord with this section must be in a format that is publicly
327 | documented (and with an implementation available to the public in
328 | source code form), and must require no special password or key for
329 | unpacking, reading or copying.
330 |
331 | 7. Additional Terms.
332 |
333 | "Additional permissions" are terms that supplement the terms of this
334 | License by making exceptions from one or more of its conditions.
335 | Additional permissions that are applicable to the entire Program shall
336 | be treated as though they were included in this License, to the extent
337 | that they are valid under applicable law. If additional permissions
338 | apply only to part of the Program, that part may be used separately
339 | under those permissions, but the entire Program remains governed by
340 | this License without regard to the additional permissions.
341 |
342 | When you convey a copy of a covered work, you may at your option
343 | remove any additional permissions from that copy, or from any part of
344 | it. (Additional permissions may be written to require their own
345 | removal in certain cases when you modify the work.) You may place
346 | additional permissions on material, added by you to a covered work,
347 | for which you have or can give appropriate copyright permission.
348 |
349 | Notwithstanding any other provision of this License, for material you
350 | add to a covered work, you may (if authorized by the copyright holders of
351 | that material) supplement the terms of this License with terms:
352 |
353 | a) Disclaiming warranty or limiting liability differently from the
354 | terms of sections 15 and 16 of this License; or
355 |
356 | b) Requiring preservation of specified reasonable legal notices or
357 | author attributions in that material or in the Appropriate Legal
358 | Notices displayed by works containing it; or
359 |
360 | c) Prohibiting misrepresentation of the origin of that material, or
361 | requiring that modified versions of such material be marked in
362 | reasonable ways as different from the original version; or
363 |
364 | d) Limiting the use for publicity purposes of names of licensors or
365 | authors of the material; or
366 |
367 | e) Declining to grant rights under trademark law for use of some
368 | trade names, trademarks, or service marks; or
369 |
370 | f) Requiring indemnification of licensors and authors of that
371 | material by anyone who conveys the material (or modified versions of
372 | it) with contractual assumptions of liability to the recipient, for
373 | any liability that these contractual assumptions directly impose on
374 | those licensors and authors.
375 |
376 | All other non-permissive additional terms are considered "further
377 | restrictions" within the meaning of section 10. If the Program as you
378 | received it, or any part of it, contains a notice stating that it is
379 | governed by this License along with a term that is a further
380 | restriction, you may remove that term. If a license document contains
381 | a further restriction but permits relicensing or conveying under this
382 | License, you may add to a covered work material governed by the terms
383 | of that license document, provided that the further restriction does
384 | not survive such relicensing or conveying.
385 |
386 | If you add terms to a covered work in accord with this section, you
387 | must place, in the relevant source files, a statement of the
388 | additional terms that apply to those files, or a notice indicating
389 | where to find the applicable terms.
390 |
391 | Additional terms, permissive or non-permissive, may be stated in the
392 | form of a separately written license, or stated as exceptions;
393 | the above requirements apply either way.
394 |
395 | 8. Termination.
396 |
397 | You may not propagate or modify a covered work except as expressly
398 | provided under this License. Any attempt otherwise to propagate or
399 | modify it is void, and will automatically terminate your rights under
400 | this License (including any patent licenses granted under the third
401 | paragraph of section 11).
402 |
403 | However, if you cease all violation of this License, then your
404 | license from a particular copyright holder is reinstated (a)
405 | provisionally, unless and until the copyright holder explicitly and
406 | finally terminates your license, and (b) permanently, if the copyright
407 | holder fails to notify you of the violation by some reasonable means
408 | prior to 60 days after the cessation.
409 |
410 | Moreover, your license from a particular copyright holder is
411 | reinstated permanently if the copyright holder notifies you of the
412 | violation by some reasonable means, this is the first time you have
413 | received notice of violation of this License (for any work) from that
414 | copyright holder, and you cure the violation prior to 30 days after
415 | your receipt of the notice.
416 |
417 | Termination of your rights under this section does not terminate the
418 | licenses of parties who have received copies or rights from you under
419 | this License. If your rights have been terminated and not permanently
420 | reinstated, you do not qualify to receive new licenses for the same
421 | material under section 10.
422 |
423 | 9. Acceptance Not Required for Having Copies.
424 |
425 | You are not required to accept this License in order to receive or
426 | run a copy of the Program. Ancillary propagation of a covered work
427 | occurring solely as a consequence of using peer-to-peer transmission
428 | to receive a copy likewise does not require acceptance. However,
429 | nothing other than this License grants you permission to propagate or
430 | modify any covered work. These actions infringe copyright if you do
431 | not accept this License. Therefore, by modifying or propagating a
432 | covered work, you indicate your acceptance of this License to do so.
433 |
434 | 10. Automatic Licensing of Downstream Recipients.
435 |
436 | Each time you convey a covered work, the recipient automatically
437 | receives a license from the original licensors, to run, modify and
438 | propagate that work, subject to this License. You are not responsible
439 | for enforcing compliance by third parties with this License.
440 |
441 | An "entity transaction" is a transaction transferring control of an
442 | organization, or substantially all assets of one, or subdividing an
443 | organization, or merging organizations. If propagation of a covered
444 | work results from an entity transaction, each party to that
445 | transaction who receives a copy of the work also receives whatever
446 | licenses to the work the party's predecessor in interest had or could
447 | give under the previous paragraph, plus a right to possession of the
448 | Corresponding Source of the work from the predecessor in interest, if
449 | the predecessor has it or can get it with reasonable efforts.
450 |
451 | You may not impose any further restrictions on the exercise of the
452 | rights granted or affirmed under this License. For example, you may
453 | not impose a license fee, royalty, or other charge for exercise of
454 | rights granted under this License, and you may not initiate litigation
455 | (including a cross-claim or counterclaim in a lawsuit) alleging that
456 | any patent claim is infringed by making, using, selling, offering for
457 | sale, or importing the Program or any portion of it.
458 |
459 | 11. Patents.
460 |
461 | A "contributor" is a copyright holder who authorizes use under this
462 | License of the Program or a work on which the Program is based. The
463 | work thus licensed is called the contributor's "contributor version".
464 |
465 | A contributor's "essential patent claims" are all patent claims
466 | owned or controlled by the contributor, whether already acquired or
467 | hereafter acquired, that would be infringed by some manner, permitted
468 | by this License, of making, using, or selling its contributor version,
469 | but do not include claims that would be infringed only as a
470 | consequence of further modification of the contributor version. For
471 | purposes of this definition, "control" includes the right to grant
472 | patent sublicenses in a manner consistent with the requirements of
473 | this License.
474 |
475 | Each contributor grants you a non-exclusive, worldwide, royalty-free
476 | patent license under the contributor's essential patent claims, to
477 | make, use, sell, offer for sale, import and otherwise run, modify and
478 | propagate the contents of its contributor version.
479 |
480 | In the following three paragraphs, a "patent license" is any express
481 | agreement or commitment, however denominated, not to enforce a patent
482 | (such as an express permission to practice a patent or covenant not to
483 | sue for patent infringement). To "grant" such a patent license to a
484 | party means to make such an agreement or commitment not to enforce a
485 | patent against the party.
486 |
487 | If you convey a covered work, knowingly relying on a patent license,
488 | and the Corresponding Source of the work is not available for anyone
489 | to copy, free of charge and under the terms of this License, through a
490 | publicly available network server or other readily accessible means,
491 | then you must either (1) cause the Corresponding Source to be so
492 | available, or (2) arrange to deprive yourself of the benefit of the
493 | patent license for this particular work, or (3) arrange, in a manner
494 | consistent with the requirements of this License, to extend the patent
495 | license to downstream recipients. "Knowingly relying" means you have
496 | actual knowledge that, but for the patent license, your conveying the
497 | covered work in a country, or your recipient's use of the covered work
498 | in a country, would infringe one or more identifiable patents in that
499 | country that you have reason to believe are valid.
500 |
501 | If, pursuant to or in connection with a single transaction or
502 | arrangement, you convey, or propagate by procuring conveyance of, a
503 | covered work, and grant a patent license to some of the parties
504 | receiving the covered work authorizing them to use, propagate, modify
505 | or convey a specific copy of the covered work, then the patent license
506 | you grant is automatically extended to all recipients of the covered
507 | work and works based on it.
508 |
509 | A patent license is "discriminatory" if it does not include within
510 | the scope of its coverage, prohibits the exercise of, or is
511 | conditioned on the non-exercise of one or more of the rights that are
512 | specifically granted under this License. You may not convey a covered
513 | work if you are a party to an arrangement with a third party that is
514 | in the business of distributing software, under which you make payment
515 | to the third party based on the extent of your activity of conveying
516 | the work, and under which the third party grants, to any of the
517 | parties who would receive the covered work from you, a discriminatory
518 | patent license (a) in connection with copies of the covered work
519 | conveyed by you (or copies made from those copies), or (b) primarily
520 | for and in connection with specific products or compilations that
521 | contain the covered work, unless you entered into that arrangement,
522 | or that patent license was granted, prior to 28 March 2007.
523 |
524 | Nothing in this License shall be construed as excluding or limiting
525 | any implied license or other defenses to infringement that may
526 | otherwise be available to you under applicable patent law.
527 |
528 | 12. No Surrender of Others' Freedom.
529 |
530 | If conditions are imposed on you (whether by court order, agreement or
531 | otherwise) that contradict the conditions of this License, they do not
532 | excuse you from the conditions of this License. If you cannot convey a
533 | covered work so as to satisfy simultaneously your obligations under this
534 | License and any other pertinent obligations, then as a consequence you may
535 | not convey it at all. For example, if you agree to terms that obligate you
536 | to collect a royalty for further conveying from those to whom you convey
537 | the Program, the only way you could satisfy both those terms and this
538 | License would be to refrain entirely from conveying the Program.
539 |
540 | 13. Remote Network Interaction; Use with the GNU General Public License.
541 |
542 | Notwithstanding any other provision of this License, if you modify the
543 | Program, your modified version must prominently offer all users
544 | interacting with it remotely through a computer network (if your version
545 | supports such interaction) an opportunity to receive the Corresponding
546 | Source of your version by providing access to the Corresponding Source
547 | from a network server at no charge, through some standard or customary
548 | means of facilitating copying of software. This Corresponding Source
549 | shall include the Corresponding Source for any work covered by version 3
550 | of the GNU General Public License that is incorporated pursuant to the
551 | following paragraph.
552 |
553 | Notwithstanding any other provision of this License, you have
554 | permission to link or combine any covered work with a work licensed
555 | under version 3 of the GNU General Public License into a single
556 | combined work, and to convey the resulting work. The terms of this
557 | License will continue to apply to the part which is the covered work,
558 | but the work with which it is combined will remain governed by version
559 | 3 of the GNU General Public License.
560 |
561 | 14. Revised Versions of this License.
562 |
563 | The Free Software Foundation may publish revised and/or new versions of
564 | the GNU Affero General Public License from time to time. Such new versions
565 | will be similar in spirit to the present version, but may differ in detail to
566 | address new problems or concerns.
567 |
568 | Each version is given a distinguishing version number. If the
569 | Program specifies that a certain numbered version of the GNU Affero General
570 | Public License "or any later version" applies to it, you have the
571 | option of following the terms and conditions either of that numbered
572 | version or of any later version published by the Free Software
573 | Foundation. If the Program does not specify a version number of the
574 | GNU Affero General Public License, you may choose any version ever published
575 | by the Free Software Foundation.
576 |
577 | If the Program specifies that a proxy can decide which future
578 | versions of the GNU Affero General Public License can be used, that proxy's
579 | public statement of acceptance of a version permanently authorizes you
580 | to choose that version for the Program.
581 |
582 | Later license versions may give you additional or different
583 | permissions. However, no additional obligations are imposed on any
584 | author or copyright holder as a result of your choosing to follow a
585 | later version.
586 |
587 | 15. Disclaimer of Warranty.
588 |
589 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
590 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
591 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
592 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
593 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
594 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
595 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
596 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
597 |
598 | 16. Limitation of Liability.
599 |
600 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
601 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
602 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
603 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
604 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
605 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
606 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
607 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
608 | SUCH DAMAGES.
609 |
610 | 17. Interpretation of Sections 15 and 16.
611 |
612 | If the disclaimer of warranty and limitation of liability provided
613 | above cannot be given local legal effect according to their terms,
614 | reviewing courts shall apply local law that most closely approximates
615 | an absolute waiver of all civil liability in connection with the
616 | Program, unless a warranty or assumption of liability accompanies a
617 | copy of the Program in return for a fee.
618 |
619 | END OF TERMS AND CONDITIONS
620 |
621 | How to Apply These Terms to Your New Programs
622 |
623 | If you develop a new program, and you want it to be of the greatest
624 | possible use to the public, the best way to achieve this is to make it
625 | free software which everyone can redistribute and change under these terms.
626 |
627 | To do so, attach the following notices to the program. It is safest
628 | to attach them to the start of each source file to most effectively
629 | state the exclusion of warranty; and each file should have at least
630 | the "copyright" line and a pointer to where the full notice is found.
631 |
632 |
633 | Copyright (C)
634 |
635 | This program is free software: you can redistribute it and/or modify
636 | it under the terms of the GNU Affero General Public License as published
637 | by the Free Software Foundation, either version 3 of the License, or
638 | (at your option) any later version.
639 |
640 | This program is distributed in the hope that it will be useful,
641 | but WITHOUT ANY WARRANTY; without even the implied warranty of
642 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
643 | GNU Affero General Public License for more details.
644 |
645 | You should have received a copy of the GNU Affero General Public License
646 | along with this program. If not, see .
647 |
648 | Also add information on how to contact you by electronic and paper mail.
649 |
650 | If your software can interact with users remotely through a computer
651 | network, you should also make sure that it provides a way for users to
652 | get its source. For example, if your program is a web application, its
653 | interface could display a "Source" link that leads users to an archive
654 | of the code. There are many ways you could offer source, and different
655 | solutions will be better for different programs; see section 13 for the
656 | specific requirements.
657 |
658 | You should also get your employer (if you work as a programmer) or school,
659 | if any, to sign a "copyright disclaimer" for the program, if necessary.
660 | For more information on this, and how to apply and follow the GNU AGPL, see
661 | .
662 |
--------------------------------------------------------------------------------
/LICENSE_header.txt:
--------------------------------------------------------------------------------
1 | bpy_jupyter
2 | Copyright (C) 2025 bpy_jupyter Project Contributors
3 |
4 | This program is free software: you can redistribute it and/or modify
5 | it under the terms of the GNU Affero General Public License as published by
6 | the Free Software Foundation, either version 3 of the License, or
7 | (at your option) any later version.
8 |
9 | This program is distributed in the hope that it will be useful,
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | GNU Affero General Public License for more details.
13 |
14 | You should have received a copy of the GNU Affero General Public License
15 | along with this program. If not, see .
16 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # `bpy_jupyter`
2 | A [Blender](https://www.blender.org/) extension fusing the flexibility of notebook-based data-viz, with the visual appeal of modern computer graphics software.
3 |
4 | ---
5 |
6 | **Documentation**:
7 |
8 | - _NOTE: The documentation link may change in the future. Stay tuned!_
9 |
10 | **Source Code**:
11 |
12 | ---
13 |
14 | > [!WARNING]
15 | > `bpy_jupyter` has reached a state of tentative usability, and should be considered **beta software** aka. **still unstable**.
16 | >
17 | > - The UI/UX may have unsolved frustrations and confusions.
18 | > - The documentation may be incomplete or unwritten.
19 | > - Tests, if they exist, have no guarantees of coverage or passing.
20 | >
21 | > We already personally find the `main` branch of `bpy_jupyter` **quite useful**, and we invite you to give it a try.
22 | > _Above all else, please be patient with us at this early stage._
23 |
24 |
25 |
26 | ## Highlights
27 | - **Blender 💗 Jupyter**: Jupyter is fantastic at reproducibly mangling data. Blender is fantastic at visualization. _It's a perfect match!_
28 | - **Minimalistic**: This extension does one thing well: Manages a Jupyter kernel embedded in Blender. _No bundled client, no opionionated servers, just a kernel!_
29 | - **Ready to Use**: Confused what exactly to do? We've written extensive user guides to help you achieve compelling results.
30 | - 🌐 **Respects your Freedoms**: `bpy_jupyter` preserves your freedom to use, modify, fork, redistribute, or even sell `bpy_jupyter`, **so long as you extend the same freedoms as you were granted** under the [AGPL](https://www.gnu.org/licenses/agpl-3.0.html) software license. _For more details, see our [License Policy](https://sorose-bpy-jupyter.pgs.sh/reference/policies/licensing.html)._
31 |
32 | **Ready to give it a try?** See [Installation](https://sorose-bpy-jupyter.pgs.sh/installation.html), then [Getting Started](https://sorose-bpy-jupyter.pgs.sh/user_guides/getting_started.html).
33 |
34 |
35 | > [!WARNING]
36 | > The documentation of `bpy_jupyter` is still a work in progress.
37 |
38 |
39 | ## Showcases
40 | - [BCon24 Demonstration](https://youtu.be/umS8jFXpC-o?feature=shared&t=81): This popular talk provides a glimpse of what's possible with this workflow.
41 | - [`bpy` Gallery](https://kolibril13.github.io/bpy-gallery/): A gallery of examples of how to leverage this workflow, including code.
42 |
43 | > [!INFO]
44 | > Doing something cool with `bpy_jupyter`?
45 | >
46 | > **Tell us about it**, and might add it to this list!
47 |
48 |
49 |
50 | ## Acknowledgements
51 | **The authors hope that you find this software useful.**
52 |
53 | This project would not be possible without the entire [Blender](https://www.blender.org/) community, across forums, DevTalk, Matrix chats, and so much more.
54 |
55 | Credit to Jan Hendrik Müller for inspiring and making this project happen.
56 | Please go watch his [BCon24 talk](https://youtu.be/umS8jFXpC-o?feature=shared)!
57 |
58 | Thanks to the Jupyter server team, who let us present an early demo of `bpy_jupyter` at [their meeting](https://github.com/jupyter-server/team-compass/issues/73#issuecomment-2610204937), and provided some great feedback.
59 |
60 | Finally, please peruse our `uv tree` of dependencies.
61 | We stand on the shoulders of giants, and could not hope to see so far without.
62 |
--------------------------------------------------------------------------------
/bpy_jupyter/__init__.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """An extension that embeds a Jupyter kernel within Blender.
18 |
19 | Attributes:
20 | BL_REGISTER: All Blender classes that should be registered by `register()`.
21 | """
22 |
23 | from . import operators, panels, preferences
24 | from .services import registration
25 | from .types import BLClass
26 |
27 | ####################
28 | # - Load and Register Addon
29 | ####################
30 | BL_REGISTER: list[type[BLClass]] = [
31 | *preferences.BL_REGISTER,
32 | *operators.BL_REGISTER,
33 | *panels.BL_REGISTER,
34 | ]
35 |
36 |
37 | ####################
38 | # - Registration
39 | ####################
40 | def register() -> None:
41 | """Registers this addon, so that its functionality is available in Blender.
42 |
43 | Notes:
44 | Called by Blender when enabling this addon.
45 |
46 | Uses `bpy_jupyter.registration.register_classes()` to register all classes collected in `BL_REGISTER`.
47 | """
48 | registration.register_classes(BL_REGISTER)
49 |
50 |
51 | def unregister() -> None:
52 | """Unregisters this addon, so that its functionality is no longer available in Blender.
53 |
54 | Notes:
55 | Run by Blender when disabling and/or uninstalling the addon.
56 |
57 | Uses `bpy_jupyter.registration.unregister_classes()` to unregister all Blender classes previously registered by this addon.
58 | """
59 | registration.unregister_classes()
60 |
--------------------------------------------------------------------------------
/bpy_jupyter/operators/__init__.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """All `bpy.types.Operator`s that ship with this extension.
18 |
19 | Attributes:
20 | BL_REGISTER: All `bpy.types.Operator`s that should be registered.
21 | """
22 |
23 | from . import copy_kern_info_to_clipboard, start_jupyter_kernel, stop_jupyter_kernel
24 |
25 | BL_REGISTER = [
26 | *start_jupyter_kernel.BL_REGISTER,
27 | *stop_jupyter_kernel.BL_REGISTER,
28 | *copy_kern_info_to_clipboard.BL_REGISTER,
29 | ]
30 |
--------------------------------------------------------------------------------
/bpy_jupyter/operators/copy_kern_info_to_clipboard.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """Implements `CopyJupyURLToClip`.
18 |
19 | Attributes:
20 | BL_REGISTER: All the Blender classes, implemented by this module, that should be registered.
21 | """
22 |
23 | import typing as typ
24 |
25 | import bpy
26 | import pyperclipfix
27 | import typing_extensions as typ_ext
28 |
29 | from ..services import jupyter_kernel
30 | from ..types import OperatorType
31 |
32 | if typ.TYPE_CHECKING:
33 | from bpy._typing import rna_enums
34 |
35 |
36 | ####################
37 | # - Constants
38 | ####################
39 | class CopyKernelInfoToClipboard(bpy.types.Operator):
40 | """Copy a value to the system clipboard.
41 |
42 | Attributes:
43 | bl_idname: Name of this operator type.
44 | bl_label: Human-oriented label for this operator.
45 | value_to_copy: Operator property containing the string to copy.
46 | """
47 |
48 | bl_idname: str = OperatorType.CopyKernelInfoToClipboard
49 | bl_label: str = 'Copy Kernel Connection Path'
50 |
51 | value_to_copy: bpy.props.StringProperty('') # pyright: ignore[reportInvalidTypeForm, reportCallIssue, reportUninitializedInstanceVariable]
52 |
53 | @typ_ext.override
54 | @classmethod
55 | def poll(cls, context: bpy.types.Context) -> bool:
56 | """Can run while a Jupyter kernel is running.
57 |
58 | Parameters:
59 | context: The current `bpy` context.
60 | _Not used._
61 | """
62 | return jupyter_kernel.is_kernel_running()
63 |
64 | @typ_ext.override
65 | def execute(
66 | self, context: bpy.types.Context
67 | ) -> set['rna_enums.OperatorReturnItems']:
68 | """Copy the path to the running connection file, to the system clipboard.
69 |
70 | Parameters:
71 | context: The current `bpy` context.
72 | _Not used._
73 | """
74 | pyperclipfix.copy(str(self.value_to_copy)) # pyright: ignore[reportUnknownArgumentType]
75 |
76 | self.report(
77 | {'INFO'},
78 | 'Copied Jupyter Kernel Value to Clipboard',
79 | )
80 | return {'FINISHED'}
81 |
82 |
83 | ####################
84 | # - Blender Registration
85 | ####################
86 | BL_REGISTER = [CopyKernelInfoToClipboard]
87 |
--------------------------------------------------------------------------------
/bpy_jupyter/operators/start_jupyter_kernel.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """Implements `StartJupyterKernel`.
18 |
19 | Attributes:
20 | BL_REGISTER: All the Blender classes, implemented by this module, that should be registered.
21 | """
22 |
23 | import typing as typ
24 | from pathlib import Path
25 |
26 | import bpy
27 | import typing_extensions as typ_ext
28 |
29 | from ..services import async_event_loop, jupyter_kernel
30 | from ..types import EXT_PACKAGE, OperatorType
31 |
32 | if typ.TYPE_CHECKING:
33 | from bpy._typing import rna_enums
34 |
35 |
36 | ####################
37 | # - Class: Start Jupyter Kernel
38 | ####################
39 | class StartJupyterKernel(bpy.types.Operator):
40 | """Start a notebook kernel, and Jupyter Lab server, from within Blender.
41 |
42 | Attributes:
43 | bl_idname: Name of this operator type.
44 | bl_label: Human-oriented label for this operator.
45 | """
46 |
47 | bl_idname: str = OperatorType.StartJupyterKernel
48 | bl_label: str = 'Start Jupyter Kernel'
49 |
50 | @typ_ext.override
51 | @classmethod
52 | def poll(cls, context: bpy.types.Context) -> bool:
53 | """Can run while a Jupyter kernel is not running.
54 |
55 | Parameters:
56 | context: The current `bpy` context.
57 | _Not used._
58 | """
59 | return not jupyter_kernel.is_kernel_running()
60 |
61 | @typ_ext.override
62 | def execute(
63 | self, context: bpy.types.Context
64 | ) -> set['rna_enums.OperatorReturnItems']:
65 | """Start an embedded jupyter kernel, as well as an `asyncio` event loop to handle kernel clients.
66 |
67 | Parameters:
68 | context: The current `bpy` context.
69 | _Not used._
70 | """
71 | path_extension_user = Path(
72 | bpy.utils.extension_path_user(
73 | EXT_PACKAGE,
74 | path='',
75 | create=True,
76 | )
77 | ).resolve()
78 |
79 | # (Re)Initialize Jupyter Kernel
80 | jupyter_kernel.init(
81 | path_connection_file=Path(
82 | path_extension_user / '.jupyter-connections' / 'connection.json'
83 | ),
84 | )
85 |
86 | # Start Jupyter Kernel and asyncio Event Loop
87 | if jupyter_kernel.IPYKERNEL is not None:
88 | jupyter_kernel.IPYKERNEL.start()
89 | async_event_loop.start()
90 |
91 | return {'FINISHED'}
92 |
93 |
94 | ####################
95 | # - Blender Registration
96 | ####################
97 | BL_REGISTER = [StartJupyterKernel]
98 |
--------------------------------------------------------------------------------
/bpy_jupyter/operators/stop_jupyter_kernel.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """Implements `StopJupyterKernel`.
18 |
19 | Attributes:
20 | BL_REGISTER: All the Blender classes, implemented by this module, that should be registered.
21 | """
22 |
23 | import typing as typ
24 |
25 | import bpy
26 | import typing_extensions as typ_ext
27 |
28 | from ..services import async_event_loop, jupyter_kernel
29 | from ..types import OperatorType
30 |
31 | if typ.TYPE_CHECKING:
32 | from bpy._typing import rna_enums
33 |
34 |
35 | ####################
36 | # - Class: Stop Jupyter Kernel
37 | ####################
38 | class StopJupyterKernel(bpy.types.Operator):
39 | """Stop a notebook kernel and Jupyter Lab server running within Blender.
40 |
41 | Attributes:
42 | bl_idname: Name of this operator type.
43 | bl_label: Human-oriented label for this operator.
44 | """
45 |
46 | bl_idname: str = OperatorType.StopJupyterKernel
47 | bl_label: str = 'Stop Jupyter Kernel'
48 |
49 | @typ_ext.override
50 | @classmethod
51 | def poll(cls, context: bpy.types.Context) -> bool:
52 | """Can run while a Jupyter kernel is running.
53 |
54 | Parameters:
55 | context: The current `bpy` context.
56 | _Not used._
57 | """
58 | return jupyter_kernel.is_kernel_running()
59 |
60 | @typ_ext.override
61 | def execute(
62 | self, context: bpy.types.Context
63 | ) -> set['rna_enums.OperatorReturnItems']:
64 | """Start the embedded jupyter kernel, as well as the `asyncio` event loop managed by this extension.
65 |
66 | Parameters:
67 | context: The current `bpy` context.
68 | _Not used._
69 | """
70 | # Stop Jupyter Kernel and asyncio Event Loop
71 | if jupyter_kernel.IPYKERNEL is not None:
72 | jupyter_kernel.IPYKERNEL.stop()
73 | async_event_loop.stop()
74 |
75 | return {'FINISHED'}
76 |
77 |
78 | ####################
79 | # - Blender Registration
80 | ####################
81 | BL_REGISTER = [StopJupyterKernel]
82 |
--------------------------------------------------------------------------------
/bpy_jupyter/panels/__init__.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """All `bpy.types.Panel`s that ship with this extension.
18 |
19 | Attributes:
20 | BL_REGISTER: All `bpy.types.Panel`s that should be registered.
21 | """
22 |
23 | from . import jupyter_panel
24 |
25 | BL_REGISTER = [
26 | *jupyter_panel.BL_REGISTER,
27 | ]
28 |
--------------------------------------------------------------------------------
/bpy_jupyter/panels/jupyter_panel.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """Implements `JupyterPanel`.
18 |
19 | Attributes:
20 | BL_REGISTER: All the Blender classes, implemented by this module, that should be registered.
21 | """
22 |
23 | import textwrap
24 | import typing as typ
25 |
26 | import bpy
27 | import pydantic as pyd
28 | import typing_extensions as typ_ext
29 |
30 | from ..services import jupyter_kernel
31 |
32 | if typ.TYPE_CHECKING:
33 | from bpy._typing import rna_enums
34 |
35 |
36 | from ..types import BLContextType, OperatorType, PanelType
37 |
38 |
39 | ####################
40 | # - Scene Properties
41 | ####################
42 | class JupyterPanel(bpy.types.Panel):
43 | """Control the Jupyter kernel launched using Blender.
44 |
45 | Attributes:
46 | bl_idname: Name of this panel type.
47 | bl_label: Human-oriented label for this panel.
48 | bl_space_type: The space to display this panel in.
49 | bl_region_type: The region to display this panel in.
50 | bl_context: Extra context guiding where this panel should be placed.
51 | """
52 |
53 | bl_idname: str = PanelType.JupyterPanel
54 | bl_label: str = 'Jupyter Kernel'
55 | bl_space_type: 'rna_enums.SpaceTypeItems' = 'PROPERTIES'
56 | bl_region_type: 'rna_enums.RegionTypeItems' = 'WINDOW'
57 | bl_context: BLContextType = 'scene' # pyright: ignore[reportIncompatibleVariableOverride]
58 |
59 | @typ_ext.override
60 | def draw(self, context: bpy.types.Context) -> None: # noqa: C901, PLR0912, PLR0915
61 | """Draw the Jupyter kernel panel, including a few options.
62 |
63 | Notes:
64 | Run by Blender when the panel needs to be displayed.
65 |
66 | Parameters:
67 | context: The Blender context object.
68 | """
69 | if context.region is None or context.preferences is None:
70 | return
71 |
72 | width_units_nrm = context.region.width / context.preferences.system.dpi
73 | width_chars = max(int(width_units_nrm / 0.11), 1)
74 |
75 | layout = self.layout
76 | if layout is None:
77 | return
78 |
79 | ####################
80 | # - Section: Respect Online Access
81 | ####################
82 | if not bpy.app.online_access:
83 | box = layout.box()
84 | col = box.column()
85 |
86 | row = col.row(align=True)
87 | row.alignment = 'CENTER'
88 | row.label(text='Online Access Disabled')
89 |
90 | col.label(text='Required for exposing kernel sockets.')
91 | col.label(text='1. Open System Preferences.')
92 | col.label(text='2. Toggle "Allow Online Access".')
93 |
94 | op = box.operator('screen.userpref_show', text='Open System Preferences')
95 | op.section = 'SYSTEM' # pyright: ignore[reportAttributeAccessIssue]
96 |
97 | ####################
98 | # - Section: Stop/Start Kernel
99 | ####################
100 | row = layout.row(align=True)
101 |
102 | col = row.column(align=True)
103 | col.enabled = bpy.app.online_access
104 | _ = col.operator(OperatorType.StartJupyterKernel, text='Start Kernel')
105 | _ = col.operator(OperatorType.StopJupyterKernel, text='Stop Kernel')
106 |
107 | col = row.column(align=True)
108 | col.scale_y = 2.0
109 | col.progress(
110 | text='Active' if jupyter_kernel.is_kernel_running() else 'Inactive',
111 | factor=1.0 if jupyter_kernel.is_kernel_running() else 0.0,
112 | )
113 |
114 | ####################
115 | # - Section: Kernel Connection
116 | ####################
117 | header, body = layout.panel(
118 | PanelType.JupyterPanel + '_connectionfile',
119 | default_closed=False,
120 | )
121 | header.label(text='Kernel Connection File')
122 | if body is not None: # pyright: ignore[reportUnnecessaryComparison]
123 | ####################
124 | # - Copy File Path | Parent Path | JSON Contents
125 | ####################
126 | col = body.column(align=True)
127 |
128 | # Copy P
129 | row = col.row(align=True)
130 | op = row.operator(
131 | OperatorType.CopyKernelInfoToClipboard,
132 | icon='COPYDOWN',
133 | text='File Path',
134 | )
135 | op.value_to_copy = ( # pyright: ignore[reportAttributeAccessIssue]
136 | str(jupyter_kernel.IPYKERNEL.path_connection_file)
137 | if jupyter_kernel.IPYKERNEL is not None
138 | and jupyter_kernel.IPYKERNEL.is_running
139 | else ''
140 | )
141 |
142 | op = row.operator(
143 | OperatorType.CopyKernelInfoToClipboard,
144 | icon='COPYDOWN',
145 | text='Parent Path',
146 | )
147 | op.value_to_copy = ( # pyright: ignore[reportAttributeAccessIssue]
148 | str(jupyter_kernel.IPYKERNEL.path_connection_file.parent)
149 | if jupyter_kernel.IPYKERNEL is not None
150 | and jupyter_kernel.IPYKERNEL.is_running
151 | else ''
152 | )
153 |
154 | op = col.operator(
155 | OperatorType.CopyKernelInfoToClipboard,
156 | icon='COPYDOWN',
157 | text='File JSON Contents',
158 | )
159 | op.value_to_copy = ( # pyright: ignore[reportAttributeAccessIssue]
160 | jupyter_kernel.IPYKERNEL.connection_info.json_str_with_key
161 | if jupyter_kernel.IPYKERNEL is not None
162 | and jupyter_kernel.IPYKERNEL.is_running
163 | else ''
164 | )
165 |
166 | ####################
167 | # - Label w/File Path
168 | ####################
169 | subheader, subbody = body.panel(
170 | PanelType.JupyterPanel + '_connectionfile_path',
171 | default_closed=True,
172 | )
173 | subheader.label(text='File Path')
174 | if subbody is not None: # pyright: ignore[reportUnnecessaryComparison]
175 | if (
176 | jupyter_kernel.IPYKERNEL is not None
177 | and jupyter_kernel.IPYKERNEL.is_running
178 | ):
179 | wrapped_path_connection_file_lines = textwrap.wrap(
180 | str(jupyter_kernel.IPYKERNEL.path_connection_file),
181 | width=width_chars,
182 | )
183 |
184 | box = subbody.box()
185 | col = box.column(align=False)
186 | col.scale_y = 0.5
187 |
188 | for line in wrapped_path_connection_file_lines:
189 | row = col.row(align=True)
190 | row.alignment = 'CENTER'
191 | row.label(text=line)
192 | else:
193 | box = subbody.box()
194 | row = box.row(align=False)
195 | row.alignment = 'CENTER'
196 | row.label(text='Kernel Inactive')
197 |
198 | ####################
199 | # - Label w/JSON Contents
200 | ####################
201 | subheader, subbody = body.panel(
202 | PanelType.JupyterPanel + '_connectionfile_json',
203 | default_closed=True,
204 | )
205 | subheader.label(text='JSON Contents')
206 | if subbody is not None: # pyright: ignore[reportUnnecessaryComparison]
207 | if (
208 | jupyter_kernel.IPYKERNEL is not None
209 | and jupyter_kernel.IPYKERNEL.is_running
210 | ):
211 | wrapped_path_connection_file_lines = textwrap.wrap(
212 | jupyter_kernel.IPYKERNEL.connection_info.json_str,
213 | width=width_chars,
214 | )
215 |
216 | box = subbody.box()
217 | col = box.column(align=False)
218 | col.scale_y = 0.5
219 |
220 | for line in wrapped_path_connection_file_lines:
221 | row = col.row(align=True)
222 | row.alignment = 'CENTER'
223 | row.label(text=line)
224 | else:
225 | box = subbody.box()
226 | row = box.row(align=False)
227 | row.alignment = 'CENTER'
228 | row.label(text='Kernel Inactive')
229 |
230 | ####################
231 | # - Section: Kernel Networking
232 | ####################
233 | header, body = layout.panel(
234 | PanelType.JupyterPanel + '_ipports',
235 | default_closed=True,
236 | )
237 | header.label(text='Kernel IP/Ports')
238 | if body is not None: # pyright: ignore[reportUnnecessaryComparison]
239 | ####################
240 | # - IP Address
241 | ####################
242 | grid = body.grid_flow(
243 | row_major=True, columns=2, even_rows=True, even_columns=True
244 | )
245 |
246 | grid.label(text='Kernel IP')
247 | grid_section = grid.column()
248 | grid_section_row = grid_section.row()
249 | grid_section_row.alignment = 'RIGHT'
250 | grid_section_row.label(
251 | text=str(jupyter_kernel.IPYKERNEL.connection_info.ip)
252 | if jupyter_kernel.IPYKERNEL is not None
253 | and jupyter_kernel.IPYKERNEL.is_running
254 | else '',
255 | icon='QUESTION' if not jupyter_kernel.is_kernel_running() else 'NONE',
256 | )
257 |
258 | op = grid_section_row.operator(
259 | OperatorType.CopyKernelInfoToClipboard, icon='COPYDOWN', text=''
260 | )
261 | op.value_to_copy = ( # pyright: ignore[reportAttributeAccessIssue]
262 | str(jupyter_kernel.IPYKERNEL.connection_info.ip)
263 | if jupyter_kernel.IPYKERNEL is not None
264 | and jupyter_kernel.IPYKERNEL.is_running
265 | else ''
266 | )
267 |
268 | ####################
269 | # - Ports
270 | ####################
271 | grid = body.grid_flow(
272 | row_major=True, columns=2, even_rows=True, even_columns=True
273 | )
274 |
275 | for label, value in zip(
276 | [
277 | 'Shell',
278 | 'IOPub',
279 | 'Stdin',
280 | 'Control',
281 | 'Heartbeat',
282 | ],
283 | [
284 | jupyter_kernel.IPYKERNEL.connection_info.shell_port,
285 | jupyter_kernel.IPYKERNEL.connection_info.iopub_port,
286 | jupyter_kernel.IPYKERNEL.connection_info.stdin_port,
287 | jupyter_kernel.IPYKERNEL.connection_info.control_port,
288 | jupyter_kernel.IPYKERNEL.connection_info.hb_port,
289 | ]
290 | if jupyter_kernel.IPYKERNEL is not None
291 | and jupyter_kernel.IPYKERNEL.is_running
292 | else 5 * ('',),
293 | strict=True,
294 | ):
295 | grid.label(text=label)
296 | grid_section = grid.column()
297 | grid_section_row = grid_section.row()
298 | grid_section_row.alignment = 'RIGHT'
299 | grid_section_row.label(
300 | text=str(value),
301 | icon='QUESTION'
302 | if not jupyter_kernel.is_kernel_running()
303 | else 'NONE',
304 | )
305 | op = grid_section_row.operator(
306 | OperatorType.CopyKernelInfoToClipboard, icon='COPYDOWN', text=''
307 | )
308 | op.value_to_copy = str(value) # pyright: ignore[reportAttributeAccessIssue]
309 |
310 | ####################
311 | # - Section: Kernel Security
312 | ####################
313 | header, body = layout.panel(
314 | PanelType.JupyterPanel + '_security',
315 | default_closed=True,
316 | )
317 | header.label(text='Kernel Security')
318 | if body is not None: # pyright: ignore[reportUnnecessaryComparison]
319 | ####################
320 | # - Security
321 | ####################
322 | grid = body.grid_flow(
323 | row_major=True, columns=2, even_rows=True, even_columns=True
324 | )
325 |
326 | for label, value in zip(
327 | [
328 | 'Key',
329 | 'Protocol',
330 | 'Sig. Algo',
331 | ],
332 | [
333 | jupyter_kernel.IPYKERNEL.connection_info.key,
334 | jupyter_kernel.IPYKERNEL.connection_info.transport,
335 | jupyter_kernel.IPYKERNEL.connection_info.signature_scheme,
336 | ]
337 | if jupyter_kernel.IPYKERNEL is not None
338 | and jupyter_kernel.IPYKERNEL.is_running
339 | else 3 * ('',),
340 | strict=True,
341 | ):
342 | grid.label(text=label)
343 | grid_section = grid.column()
344 | grid_section_row = grid_section.row()
345 | grid_section_row.alignment = 'RIGHT'
346 | grid_section_row.label(
347 | text=str(value),
348 | icon='QUESTION'
349 | if not jupyter_kernel.is_kernel_running()
350 | else 'NONE',
351 | )
352 |
353 | # Special Case: Allow Copying Security-Sensitive Values
354 | ## An attacker with access to Blender's memory could get it anyway.
355 | ## Thus, there's no good reason to keep it from the operator.
356 | if isinstance(value, pyd.SecretStr):
357 | op = grid_section_row.operator(
358 | OperatorType.CopyKernelInfoToClipboard, icon='COPYDOWN', text=''
359 | )
360 | op.value_to_copy = str(value.get_secret_value()) # pyright: ignore[reportAttributeAccessIssue]
361 | else:
362 | op = grid_section_row.operator(
363 | OperatorType.CopyKernelInfoToClipboard, icon='COPYDOWN', text=''
364 | )
365 | op.value_to_copy = str(value) # pyright: ignore[reportAttributeAccessIssue]
366 |
367 |
368 | ####################
369 | # - Blender Registration
370 | ####################
371 | BL_REGISTER = [JupyterPanel]
372 |
--------------------------------------------------------------------------------
/bpy_jupyter/preferences.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """Addon preferences, encapsulating the various global modifications that the user may make to how this addon functions.
18 |
19 | Attributes:
20 | BL_REGISTER: All Blender classes from this module that should be registered.
21 | """
22 |
23 | import bpy
24 |
25 | from .types import EXT_PACKAGE
26 |
27 |
28 | ####################
29 | # - Class: Preferences
30 | ####################
31 | class BPYJupyterAddonPrefs(bpy.types.AddonPreferences):
32 | """Manages user preferences and settings for this addon.
33 |
34 | Attributes:
35 | bl_idname: Matches `__package__`.
36 | """
37 |
38 | bl_idname: str = EXT_PACKAGE
39 |
40 |
41 | ####################
42 | # - Blender Registration
43 | ####################
44 | BL_REGISTER = [BPYJupyterAddonPrefs]
45 |
--------------------------------------------------------------------------------
/bpy_jupyter/services/__init__.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """All independent, stateful utilities that ship with this extension."""
18 |
--------------------------------------------------------------------------------
/bpy_jupyter/services/async_event_loop.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """Manages an `asyncio` event loop, which allows running asynchronous extension code in the main thread of Blender.
18 |
19 | ## Motivation
20 | Blender's Python API is not thread safe, meaning that the main thread must be used to update all ex. properties, UI elements, etc. .
21 | At the same time, when Python code runs in Blender's main thread, the UI becomes unresponsive until it is finished.
22 | What to do?
23 |
24 | Of course, many salient use cases **require** interacting with the main thread, yet **do not constantly require** the CPU's attention:
25 |
26 | - **Network Client**: Waiting for responses from a network server, after making a request.
27 | - For instance, a progress bar that responds to updates from a cloud-service ex. a render farm, expensive physics simulation, etc. .
28 | - **Network Server**: Waiting for clients to connect to us,
29 | - For instance, a mini web-service enabling IDE shortcuts that trigger actions within a running Blender.
30 | - **Input Processing**: Waiting for input from some kind of input device.
31 | - For instance, an addon that maps game controller buttons to Blender properties, or MIDI sliders to rig properties.
32 | - **IPC**: Waiting for status updates from an external process, started via ex. `subprocess` or `multiprocessing`.
33 | - For instance, monitoring a computationally heavy external command - or simply switching between light/dark mode in response to theming signals on a Linux system's `dbus`!
34 |
35 | By inelegantly slapping an `asyncio` event loop on top of Blender's main thread, any code that spends most of its time "just waiting" can now `await` whatever it needs to, without blocking Blender's main thread.
36 |
37 | ## Limitations
38 | It's worth saying: **Concurrency is not parallelism**.
39 |
40 | When using this system, _all `async` code still runs in the main thread_.
41 | If that code uses a lot of CPU processing, then **it will block that main thread and freeze Blender's UI**.
42 |
43 | To run expensive code "in the background", one should use the right tools for the job, such as `multiprocessing`.
44 | The `async` part only comes into play when ex. `await`ing messages from that external process to update the extension's UI.
45 |
46 |
47 | Attributes:
48 | EVENT_LOOP_TIMEOUT_SEC: Number of seconds between each iteration of the `asyncio` event loop.
49 | """
50 |
51 | import asyncio
52 |
53 | import bpy
54 |
55 | ####################
56 | # - Constants
57 | ####################
58 | EVENT_LOOP_TIMEOUT_SEC = 0.001
59 |
60 |
61 | ####################
62 | # - Event Loop
63 | ####################
64 | @bpy.app.handlers.persistent
65 | def increment_event_loop() -> float:
66 | """Run one iteration of the `asyncio` event loop.
67 |
68 | ## Mechanism
69 | The hack at work here is thus: Blender's event loop is asked to increment the `asyncio` event loop "very often".
70 |
71 | Each time `increment_event_loop` is called, all pending (non-`await`ing) tasks will run until they either finish, or reach an `await`.
72 | This is the meaning of "one iteration", and this is achieved using `loop.call_soon(loop.stop)`, then `loop.run_forever()`.
73 |
74 | Since the event loop retains its state, and ability to accept tasks, after `loop.stop()`, doing this repeatedly amounts to a frequently invoked "pause and flush".
75 |
76 | Notes:
77 | **To enable**, use `bpy.app.timers.register(increment_event_loop, persistent=True)`.
78 |
79 | Returns:
80 | The number of seconds to wait before running this function again.
81 | """
82 | loop = asyncio.get_event_loop()
83 | _ = loop.call_soon(loop.stop)
84 | loop.run_forever()
85 |
86 | return EVENT_LOOP_TIMEOUT_SEC
87 |
88 |
89 | ####################
90 | # - Start
91 | ####################
92 | def start() -> None:
93 | """Start the `asyncio` event loop.
94 |
95 | Notes:
96 | Registers `increment_event_loop` to `bpy.app.timers`.
97 |
98 | **DO NOT** run if an event loop has already been started using `start()`.
99 | """
100 | bpy.app.timers.register(increment_event_loop, persistent=True)
101 |
102 |
103 | def stop():
104 | """Stop a running `asyncio` event loop.
105 |
106 | Notes:
107 | Unregisters `increment_event_loop` from `bpy.app.timers`.
108 |
109 | **DO NOT** run if an event loop has not already been started using `start()`.
110 | """
111 | bpy.app.timers.unregister(increment_event_loop)
112 |
--------------------------------------------------------------------------------
/bpy_jupyter/services/jupyter_kernel.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """Manages a global instance of an embedded `ipython` kernel, as implemented by `bpy_jupyter.utils.IPyKernel`.
18 |
19 | Notes:
20 | **Must** be used together with `bpy_jupyter.services.async_event_loop`, or some other implementation of an `asyncio` event loop.
21 |
22 | If this is not done, then the embedded kernel will be unable to act on incoming requests.
23 | Instead, such requests will hang forever / until timing out.
24 |
25 | Attributes:
26 | IPYKERNEL: An instance of the embedded `ipython` kernel.
27 | """
28 |
29 | from pathlib import Path
30 |
31 | from ..utils.ipykernel import IPyKernel
32 |
33 | ####################
34 | # - Globals
35 | ####################
36 | IPYKERNEL: IPyKernel | None = None
37 |
38 |
39 | ####################
40 | # - Lifecycle
41 | ####################
42 | def init(*, path_connection_file: Path) -> None:
43 | """Initialize the IPyKernel using the given connection file path.
44 |
45 | Notes:
46 | This is merely a setup function.
47 |
48 | The kernel is not actually started until `IPYKERNEL.start()` is called.
49 |
50 | Parameters:
51 | path_connection_file: Path to the kernel connection file.
52 | """
53 | global IPYKERNEL # noqa: PLW0603
54 |
55 | if IPYKERNEL is None or not IPYKERNEL.is_running:
56 | IPYKERNEL = IPyKernel(path_connection_file=path_connection_file) # pyright: ignore[reportConstantRedefinition]
57 |
58 | elif IPYKERNEL.is_running:
59 | msg = "Can't re-initialize `IPYKERNEL`, since it is running."
60 | raise ValueError(msg)
61 |
62 |
63 | ####################
64 | # - Information
65 | ####################
66 | def is_kernel_running() -> bool:
67 | """Whether the kernel is both initialized and running.
68 |
69 | Notes:
70 | Use this to check the kernel state from `poll()` methods, since it also takes the uninitialized `IPYKERNEL is None` state into account.
71 |
72 | Returns:
73 | Whether the underlying `IPYKERNEL` is both initialized (aka. not `None`), and running (aka. `IPYKERNEL.is_running`).
74 | """
75 | return IPYKERNEL is not None and IPYKERNEL.is_running
76 |
--------------------------------------------------------------------------------
/bpy_jupyter/services/registration.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """Manages the registration of Blender classes.
18 |
19 | Attributes:
20 | _REGISTERED_CLASSES: Blender classes currently registered by this addon, indexed by `bl_idname`.
21 | """
22 |
23 | import collections.abc as cabc
24 |
25 | import bpy
26 |
27 | from ..types import BLClass
28 |
29 | ####################
30 | # - Globals
31 | ####################
32 | _REGISTERED_CLASSES = dict[str, type[BLClass]]()
33 |
34 |
35 | ####################
36 | # - Class Registration
37 | ####################
38 | def register_classes(bl_classes: cabc.Sequence[type[BLClass]]) -> None:
39 | """Registers a list of Blender classes.
40 |
41 | Notes:
42 | If a class is already registered (aka. its `bl_idname` already has an entry), then its registration is skipped.
43 |
44 | Parameters:
45 | bl_classes: List of Blender classes to register.
46 | """
47 | for cls in bl_classes:
48 | if cls.bl_idname in _REGISTERED_CLASSES:
49 | continue
50 |
51 | bpy.utils.register_class(cls)
52 | _REGISTERED_CLASSES[cls.bl_idname] = cls
53 |
54 |
55 | def unregister_classes() -> None:
56 | """Unregisters all previously registered Blender classes."""
57 | for cls in reversed(_REGISTERED_CLASSES.values()):
58 | bpy.utils.unregister_class(cls)
59 |
60 | _REGISTERED_CLASSES.clear()
61 |
--------------------------------------------------------------------------------
/bpy_jupyter/types.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """Types, enums and constants for use throughout this extension.
18 |
19 | Attributes:
20 | BLClass: A Blender class in `bpy.types` that can be registered.
21 | BLContextType: A possible value for `bl_context` in `bpy.types.Panel` types.
22 | PATH_MANIFEST: Path to this addon's `blender_manifest.toml` file.
23 | MANIFEST: This addon's `blender_manifest.toml` as a dictionary.
24 | EXT_NAME: Name of this extension.
25 | EXT_PACKAGE: Value of `__package__` on the top level of this extension.
26 | PANEL_TYPE_PREFIX: Extension-specific prefix to use for all values in `PanelType`.
27 |
28 | References:
29 | - Deducing Valid `bl_context`:
30 | """
31 |
32 | import enum
33 | import tomllib
34 | import typing as typ
35 | from pathlib import Path
36 |
37 | import bpy
38 |
39 | if __package__ is None:
40 | msg = "Extension `__package__` is `None`. This shouldn't be possible in a Blender extension."
41 | raise RuntimeError(msg)
42 |
43 | ####################
44 | # - Types
45 | ####################
46 | BLClass: typ.TypeAlias = (
47 | bpy.types.Panel
48 | | bpy.types.UIList
49 | | bpy.types.Menu
50 | | bpy.types.Header
51 | | bpy.types.Operator
52 | | bpy.types.KeyingSetInfo
53 | | bpy.types.RenderEngine
54 | | bpy.types.AssetShelf
55 | | bpy.types.FileHandler
56 | | bpy.types.AddonPreferences
57 | )
58 | BLContextType: typ.TypeAlias = typ.Literal[
59 | '.armature_edit',
60 | '.curves_sculpt',
61 | '.grease_pencil_paint',
62 | '.greasepencil_paint',
63 | '.greasepencil_sculpt',
64 | '.greasepencil_vertex',
65 | '.greasepencil_weight',
66 | '.imagepaint',
67 | '.imagepaint_2d',
68 | '.mesh_edit',
69 | '.objectmode',
70 | '.paint_common',
71 | '.paint_common_2d',
72 | '.particlemode',
73 | '.posemode',
74 | '.sculpt_mode',
75 | '.uv_sculpt',
76 | '.vertexpaint',
77 | '.weightpaint',
78 | 'addons',
79 | 'animation',
80 | 'bone',
81 | 'bone_constraint',
82 | 'collection',
83 | 'constraint',
84 | 'data',
85 | 'editing',
86 | 'experimental',
87 | 'extensions',
88 | 'file_paths',
89 | 'input',
90 | 'interface',
91 | 'keymap',
92 | 'lights',
93 | 'material',
94 | 'modifier',
95 | 'navigation',
96 | 'object',
97 | 'output',
98 | 'particle',
99 | 'physics',
100 | 'render',
101 | 'save_load',
102 | 'scene',
103 | 'shaderfx',
104 | 'system',
105 | 'texture',
106 | 'themes',
107 | 'view_layer',
108 | 'viewport',
109 | 'world',
110 | ]
111 |
112 | ####################
113 | # - Load Manifest
114 | ####################
115 | PATH_MANIFEST: Path = Path(__file__).resolve().parent / 'blender_manifest.toml'
116 |
117 | with PATH_MANIFEST.open('rb') as f:
118 | MANIFEST: dict[str, typ.Any] = tomllib.load(f)
119 |
120 | EXT_NAME: str = MANIFEST['id']
121 | EXT_PACKAGE: str = __package__
122 |
123 | ####################
124 | # - Panel Type
125 | ####################
126 | PANEL_TYPE_PREFIX = f'{EXT_NAME.upper()}_PT_'
127 |
128 |
129 | class PanelType(enum.StrEnum):
130 | """`bl_idname` values for all addon-defined `bpy.types.Panel`s.
131 |
132 | Attributes:
133 | JupyterPanel: The `Properties -> Scene` panel that allows managing the embedded Jupyter kernel.
134 | """
135 |
136 | JupyterPanel = f'{PANEL_TYPE_PREFIX}jupyter_panel'
137 |
138 |
139 | ####################
140 | # - Operator Type
141 | ####################
142 | class OperatorType(enum.StrEnum):
143 | """`bl_idname` values for all addon-defined `bpy.types.Operator`s.
144 |
145 | Attributes:
146 | StartJupyterKernel: Starts an embedded Jupyter kernel, using `bpy_jupyter.services.jupyter_kernel`.
147 |
148 | - Also starts an `asyncio` event loop, using `bpy_jupyter.services.async_event_loop`.
149 | StopJupyterKernel: Stops the embedded Jupyter kernel, using `bpy_jupyter.services.jupyter_kernel`.
150 |
151 | - Also stops the active `asyncio` event loop, using `bpy_jupyter.services.async_event_loop`.
152 | CopyKernelInfoToClipboard: Copies some string whose value depends on a running Jupyter kernel, to the system clipboard.
153 | """
154 |
155 | StartJupyterKernel = f'{EXT_NAME}.start_jupyter_kernel'
156 | StopJupyterKernel = f'{EXT_NAME}.stop_jupyter_kernel'
157 | CopyKernelInfoToClipboard = f'{EXT_NAME}.copy_kernel_info_to_clipboard'
158 |
--------------------------------------------------------------------------------
/bpy_jupyter/utils/__init__.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """All independent, stateless utilities that ship with this extension."""
18 |
--------------------------------------------------------------------------------
/bpy_jupyter/utils/ipykernel.py:
--------------------------------------------------------------------------------
1 | # bpy_jupyter
2 | # Copyright (C) 2025 bpy_jupyter Project Contributors
3 | #
4 | # This program is free software: you can redistribute it and/or modify
5 | # it under the terms of the GNU Affero General Public License as published by
6 | # the Free Software Foundation, either version 3 of the License, or
7 | # (at your option) any later version.
8 | #
9 | # This program is distributed in the hope that it will be useful,
10 | # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | # GNU Affero General Public License for more details.
13 | #
14 | # You should have received a copy of the GNU Affero General Public License
15 | # along with this program. If not, see .
16 |
17 | """Utilities making it easy to embed an `ipykernel` inside of another Python process.
18 |
19 | References:
20 | - IPyKernel Options:
21 |
22 | See Also:
23 | - Wrapper Kernels:
24 | - Jupyter Lab w/Existing Kernels:
25 | """
26 |
27 | import contextlib
28 | import functools
29 | import gc
30 | import ipaddress
31 | import json
32 | import sys
33 | import threading
34 | import typing as typ
35 | from pathlib import Path
36 |
37 | import pydantic as pyd
38 | import zmq
39 | from ipykernel.kernelapp import IPKernelApp
40 |
41 |
42 | ####################
43 | # - Class: Connection INfo
44 | ####################
45 | class JupyterKernelConnectionInfo(pyd.BaseModel, frozen=True):
46 | """Structure that completely defines how to communicate with a running Jupyter kernel.
47 |
48 | Notes:
49 | This is directly analogous, and is in fact parsed directly from, the conventional "connection file".
50 |
51 | Attributes:
52 | kernel_name: Name of the kernel.
53 | ip: The IP address that the kernel binds ports to.
54 | shell_port: Port of the kernel shell socket.
55 | iopub_port: Port of the kernel iopub socket.
56 | stdin_port: Port of the kernel stdin socket.
57 | control_port: Port of the kernel control socket.
58 | hb_port: Port of the kernel heartbeat socket.
59 | key: Secret key that should be used to authenticate with the kernel.
60 | transport: Protocol that should be used to communicate with the kernel.
61 | signature_scheme: Cipher suite that should be used to validate message authenticity.
62 |
63 | """
64 |
65 | ip: ipaddress.IPv4Address | ipaddress.IPv4Address
66 |
67 | shell_port: int
68 | iopub_port: int
69 | stdin_port: int
70 | control_port: int
71 | hb_port: int
72 |
73 | key: pyd.SecretStr
74 | transport: typ.Literal['tcp']
75 | signature_scheme: typ.Literal['hmac-sha256']
76 |
77 | kernel_name: str
78 |
79 | @functools.cached_property
80 | def json_str(self) -> str:
81 | """The JSON string corresponding to this model.
82 |
83 | Notes:
84 | `self.key` is not directly included; rather a placeholder of `****`'s are included instead.
85 |
86 | If including the real `self.key` is important, please use `self.json_str_with_key`.
87 | """
88 | model_dict = self.model_dump(mode='json')
89 | return json.dumps(model_dict)
90 |
91 | @functools.cached_property
92 | def json_str_with_key(self) -> str:
93 | """The JSON string corresponding to this model, including the true value of `self.key`.
94 |
95 | Notes:
96 | **Use of this property should be minimized**, as the exposure of `self.key` in ex. logs may compromise the security of the kernel.
97 | """
98 | model_dict = self.model_dump(mode='json')
99 | model_dict['key'] = self.key.get_secret_value()
100 | return json.dumps(model_dict)
101 |
102 | @classmethod
103 | def from_path_connection_file(cls, path_connection_file: Path) -> typ.Self:
104 | """Construct from a Jupyter kernel connection file, including `self.key`."""
105 | with path_connection_file.open('r') as f:
106 | return cls(**json.load(f))
107 |
108 |
109 | ####################
110 | # - Class: IPyKernel
111 | ####################
112 | class IPyKernel(pyd.BaseModel):
113 | """An embeddable `ipykernel`, which wraps `ipykernel.kernelapp.IPKernelApp` in a clean, friendly interface.
114 |
115 | Attributes:
116 | path_connection_file: Path to the connection file to create
117 | _`.start()` will overwrite this file._
118 |
119 | _lock: Blocks the use of `_is_running` while `.start()` or `.stop()` are working.
120 | _kernel_app: Running embedded `IPKernelApp`, if any is running.
121 |
122 | """
123 |
124 | path_connection_file: Path
125 |
126 | ####################
127 | # - Internal State
128 | ####################
129 | _lock: threading.Lock = pyd.PrivateAttr(default_factory=lambda: threading.Lock())
130 | _kernel_app: IPKernelApp | None = pyd.PrivateAttr(default=None)
131 |
132 | ####################
133 | # - Properties: Locked
134 | ####################
135 | @functools.cached_property
136 | def is_running(self) -> bool:
137 | """Whether this Jupyter kernel is currently running."""
138 | with self._lock:
139 | return self._kernel_app is not None
140 |
141 | @functools.cached_property
142 | def connection_info(self) -> JupyterKernelConnectionInfo:
143 | """Parsed kernel connection file for the currently running Jupyter kernel."""
144 | with self._lock:
145 | if self._kernel_app is not None:
146 | return JupyterKernelConnectionInfo.from_path_connection_file(
147 | self.path_connection_file
148 | )
149 | msg = "Connection information can't be parsed for IPyKernel, since it's not running."
150 | raise ValueError(msg)
151 |
152 | ####################
153 | # - Methods: Lifecycle
154 | ####################
155 | def start(self) -> None:
156 | """Start this Jupyter kernel.
157 |
158 | Notes:
159 | An `asyncio` event loop **must be available** before kernel requests can be handled, since the embedded `IPKernelApp` uses this to `await` client requests.
160 |
161 | Raises:
162 | ValueError: If an `IPyKernel` is already running.
163 | """
164 | with self._lock:
165 | if self._kernel_app is None:
166 | # Reset the Cached Property
167 | # - First new use will wait for the lock we currently hold.
168 | with contextlib.suppress(AttributeError):
169 | del self.is_running
170 | del self.connection_info
171 |
172 | ####################
173 | # - Start the Kernel w/o sys.stdout Suppression
174 | ####################
175 | self._kernel_app = IPKernelApp.instance(
176 | connection_file=str(self.path_connection_file),
177 | quiet=False,
178 | )
179 | self._kernel_app.initialize([sys.executable])
180 | self._kernel_app.kernel.start()
181 |
182 | else:
183 | msg = "IPyKernel can't be started, since it's already running."
184 | raise ValueError(msg)
185 |
186 | def stop(self) -> None:
187 | """Stop this Jupyter kernel.
188 |
189 | Notes:
190 | Unfortunately, `IPKernelApp` doesn't provide any kind of `stop()` function.
191 | Therefore, this method involves a LOT of manual hijinks and hacks used in order to cleanly stop and vacuum the running kernel.
192 |
193 | Raises:
194 | ValueError: If an `IPyKernel` is not already running.
195 | RuntimeErorr: If the `IPKernelApp` doesn't shut down before the timeout.
196 |
197 | References:
198 | - `traitlets.config.SingletonConfigurable`:
199 | - `ZMQStream.flush()`:
200 | - `zmq.Socket.setsockopt()`:
201 | - `zmq_setsockopt` Options:
202 | - `IPKernel` Initialization:
203 | - `IPKernelApp.close()`:
204 | - `IPKernel.shell_class` Instancing:
205 |
206 | See Also:
207 | - Illustrative `FIXME` for Kernel Stop in `ipykernel/gui/gtkembed.py`:
208 | - `ZMQ_TCP_KEEPALIVE` Workaround for Lingering FDs:
209 | - `man 7 tcp` on Linux:
210 | """
211 | # Dear Reviewer: You'll see some sketchy things in here.
212 | ## That doesn't mean it isn't nice!
213 | with self._lock:
214 | if self._kernel_app is not None:
215 | # Reset the Cached Property
216 | # - First new use will wait for the lock we currently hold.
217 | with contextlib.suppress(AttributeError):
218 | del self.is_running
219 | del self.connection_info
220 |
221 | ####################
222 | # - Gently Shutdown the Kernel
223 | ####################
224 | # Like a pidgeon crash-landing on a lillypad in a pond.
225 | # Then getting eaten by an oversized frog.
226 | # Who lived on that lillypad. Ergo the irritation.
227 |
228 | # Don't delete this print.
229 | ## Things break if one deletes this print.
230 | ## Yes, things are otherwise robust (so far)!
231 | ## ...Unless this print is removed.
232 | print('', end='') # noqa: T201
233 |
234 | # This part is superstition.
235 | ## Isn't a little little insanity little warranted?
236 | ## Read the rest of this method before you answer.
237 | _ = self._kernel_app.shell_socket.setsockopt(
238 | zmq.SocketOption.LINGER,
239 | 0,
240 | )
241 | _ = self._kernel_app.control_socket.setsockopt( # pyright: ignore[reportUnknownVariableType]
242 | zmq.SocketOption.LINGER,
243 | 0,
244 | )
245 | _ = self._kernel_app.debugpy_socket.setsockopt( # pyright: ignore[reportUnknownVariableType]
246 | zmq.SocketOption.LINGER,
247 | 0,
248 | )
249 | _ = self._kernel_app.debug_shell_socket.setsockopt( # pyright: ignore[reportUnknownVariableType]
250 | zmq.SocketOption.LINGER,
251 | 0,
252 | )
253 | _ = self._kernel_app.stdin_socket.setsockopt(
254 | zmq.SocketOption.LINGER,
255 | 0,
256 | )
257 | _ = self._kernel_app.iopub_socket.setsockopt( # pyright: ignore[reportUnknownVariableType]
258 | zmq.SocketOption.LINGER,
259 | 0,
260 | )
261 |
262 | # Clear the Shell Environment Singleton
263 | ## Reason: Otherwise, kernel stop/start retains state ex. set variables.
264 | ## Singletons are, after all, magically resurrected.
265 | ## OOP was a mistake.
266 | self._kernel_app.kernel.shell_class.clear_instance()
267 |
268 | # Flush and close all the ZMQ streams manually.
269 | ## Reason: Otherwise, ZMQSocket file descriptors don't close.
270 | ## We make sure the streams get LINGER=0, which might propagate to the socket.
271 | ## So the above LINGER's are more like defensive driving - erm, coding.
272 | self._kernel_app.kernel.shell_stream.flush()
273 | self._kernel_app.kernel.shell_stream.close(linger=0)
274 | self._kernel_app.kernel.control_stream.flush()
275 | self._kernel_app.kernel.control_stream.close(linger=0)
276 | self._kernel_app.kernel.debugpy_stream.flush()
277 | self._kernel_app.kernel.debugpy_stream.close(linger=0)
278 |
279 | # Trigger the Official close(). It does a lot. It is not sufficient.
280 | ## It does a lot. It is far from sufficient.
281 | ## The ordering of when this is called was determined by brute-force testing.
282 | ## One important thing that happens is .reset_io(), which restores sys.std*.
283 | self._kernel_app.close() # type: ignore[no-untyped-call]
284 | ## NOTE: Likely, the magic print() above flushes something important...
285 | ## ...which allows .reset_io() to succeed in restoring the sys.std*'s.
286 | ## "Just" flushing stdout/stderr wasn't good enough.
287 | ## So the print() remains.
288 |
289 | # Manual: Close Connection File
290 | ## Reason: Otherwise, the connection.json file just sticks around forever.
291 | ## Best to delete it so nobody can use it, since its claims are no longer valid.
292 | self._kernel_app.cleanup_connection_file()
293 |
294 | # Clear Singleton Instances
295 | ## Reason: Otherwise, the now-defunct IPKernel and IPKernelApp are resurrected.
296 | ## Singletons are, after all, magically resurrected.
297 | ## OOP was a mistake.
298 | self._kernel_app.kernel.clear_instance()
299 | self._kernel_app.clear_instance()
300 |
301 | # Delete the KernelApp
302 | ## Reason: The semantics of `del` w/0 refs can often be more concrete.
303 | ## Another example of defensive coding.
304 | _kernel = self._kernel_app
305 | self._kernel_app = None
306 | del _kernel
307 |
308 | # Force a Global GC
309 | ## Reason: We just orphaned a bunch of refs which may monopolize system resources.
310 | ## Examples: Lingering FDs. Whatever the user executed in `shell_class`.
311 | ## "Delete whenever" feels insufficient. Whatever ought to go should go now.
312 | _ = gc.collect()
313 |
314 | else:
315 | msg = "IPyKernel can't be stopped, since it's not running."
316 | raise ValueError(msg)
317 |
--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
1 | ../README.md
--------------------------------------------------------------------------------
/docs/installation.md:
--------------------------------------------------------------------------------
1 | !!! abstract
2 | Easily install the `bpy_jupyter` extension.
3 |
4 | **Ready to use `bpy_jupyter`?** See [User Guides / Getting Started](./user_guides/getting_started.md).
5 |
6 | # Installation
7 | To install `bpy_jupyter`, [Blender 3D](https://www.blender.org/) must already be installed.
8 |
9 | ### Install from `extensions.blender.org`
10 | !!! warning
11 | This method is planned, but not yet implemented.
12 |
13 | Stay tuned!
14 |
15 | ### Install from GitHub Release
16 | Navigate to the [`bpy_jupyter` GitHub releases](https://github.com/Octoframes/bpy_jupyter/releases), and download the build extension `.zip` corresponding to your platform.
17 |
18 | After downloading, drag-and-drop the `.zip` file into Blender to install it.
19 |
20 | ### Install from Source
21 | !!! warning "Warning: `uv` Required"
22 | It is **strongly suggested** to install [`uv`](https://docs.astral.sh/uv/) before following this installation method, using the [`uv` installation guide](https://docs.astral.sh/uv/getting-started/installation/).
23 |
24 | !!! tip
25 | `bpy_jupyter` is built using an unreleased preview version of the `blext` tool.
26 |
27 | As `blext` matures, this section may change.
28 | Stay tuned!
29 |
30 | First, clone the repository using `git`:
31 | ```bash
32 | git clone https://github.com/Octoframes/bpy_jupyter.git
33 | cd bpy_jupyter
34 | ```
35 |
36 | You can now `git checkout` a particular commit, or simply stick to the latest commit on `main`.
37 |
38 | Either way, to run `bpy_jupyter` in your locally installed Blender, execute the following within the cloned repository:
39 | ```
40 | $ uv run --locked blext run
41 | ```
42 |
43 | To build `.zip` files for all supported platforms and Blender versions, execute the following:
44 | ```
45 | $ uv run --locked blext run
46 | ```
47 |
48 | The extension `.zip`s will be available in the `build/` folder of the project root, from where they can be drag-and-dropped into Blender for installation.
49 |
--------------------------------------------------------------------------------
/docs/reference/contributing.md:
--------------------------------------------------------------------------------
1 | # Contributing
2 | !!! success "Cross-Platform Support"
3 | This guide is designed to work on all major operating systems:
4 |
5 | - On Linux and MacOS, use of the `bash` shell is presumed.
6 | - On Windows, use of `Powershell` is presumed (although `cmd` may work too).
7 |
8 | ## Prerequisites
9 | To work with `bpy_jupyter`, you'll need:
10 |
11 | 0. Blender: Please see the [official Blender website](https://www.blender.org/).
12 | 1. `git`: Please see the [official `git` homepage](https://git-scm.com/).
13 | 2. `uv`: Please see the [`uv` installation guide](https://docs.astral.sh/uv/getting-started/installation/).
14 | 3. `commitizen` w/`cz-conventional-gitmoji`: Please refer to the [official `commitizen` documentation](https://commitizen-tools.github.io/commitizen/).
15 |
16 | After `uv` is installed, `commitizen` is easily installed by running:
17 | ```bash
18 | uv tool install commitizen --with cz-conventional-gitmoji
19 | ```
20 |
21 |
22 | ### Cloning the Repository
23 | Next, you'll need to **clone the repository**.
24 |
25 | Navigate to your favorite directory and run:
26 | === "SSH"
27 | ```bash
28 | git clone https://github.com/Octoframes/bpy_jupyter.git
29 | ```
30 | === "HTTPS"
31 | ```bash
32 | git clone git@github.com:Octoframes/bpy_jupyter.git
33 | ```
34 |
35 | Then, enter the project:
36 | ```bash
37 | cd bpy_jupyter
38 | ```
39 |
40 | You can now modify whatever files you want to!
41 | Before making any changes, however, you should probably create a branch:
42 | ```bash
43 | git checkout -b my-cool-branch
44 | ```
45 |
46 |
47 |
48 | ### Installing `pre-commit` Hooks
49 | The easiest way to make sure your commits adhere to all `bpy_jupyter` standards is to install the `pre-commit` hooks:
50 |
51 | ```bash
52 | uv run pre-commit install
53 | ```
54 |
55 | To test this, you can always run all `pre-commit` hooks on all files using:
56 | ```bash
57 | uv run pre-commit run --all-files
58 | ```
59 |
60 |
61 |
62 | ## 30,000ft Overview
63 | ### General Code Structure
64 | The structure of the extension package itself is thus:
65 | ```
66 | bpy_jupyter/
67 | | ...
68 | | bpy_jupyter/
69 | | | __init__.py --> Extension entrypoint
70 | | | preferences.py --> Addon preferences
71 | | | ...
72 | | | operators/ --> bpy.types.Operator types go here.
73 | | | panels/ --> bpy.types.Panel types go here.
74 | | | services/ --> Independent resources with state.
75 | | | utils/ --> Independent resources without state.
76 | ```
77 |
78 | The following root-level files have particular importance.
79 |
80 | - `README.md`: The first text seen on the GitHub homepage. _Also, this doubles as `index.md` in the documentation._
81 | - `pyproject.toml`: Configures the extension (incl. `blender_manifest.toml`) and all tooling.
82 | - `uv.lock`: Specifies the specific dependency versions that the extension (and dev tools) must have.
83 | - `mkdocs.yml`: Configures the documentation website.
84 | - `.editorconfig`: Formalizes conventions for ex. indentation per filetype.
85 | - `.gitignore`: Formalizes what should **not** be checked into `git`.
86 | - `CHANGELOG.md`: **Do not edit by hand**. Instead, auto-generate using `cz changelog`
87 | - `LICENSE_header`: License header that `pre-commit` inserts into all `.py` files.
88 |
89 |
90 |
91 | ### Development Tools
92 | !!! note
93 | All tools listed here are development dependencies of `bpy_jupyter`.
94 | This means that they don't need to be installed, don't ship with the extension, but can nonetheless be accessed using:
95 | ```bash
96 | uv run {program}
97 | ```
98 |
99 | For example, `uv run ruff check` would run `bpy_jupyter`'s version of `ruff`.
100 |
101 | For static analysis, `bpy_jupyter` uses the following tools:
102 |
103 | - `ruff check`: A fast linter that replaces many other tools. For more, see the [`ruff` documentation](https://docs.astral.sh/ruff/).
104 | - `ruff format`: A fast `black`-inspired code formatter. For more, see the [`ruff` documentation](https://docs.astral.sh/ruff/).
105 | - `basedpyright`: Fork of the standard `pyright` type checker. For more, see the [`basedpyright` documentation](https://docs.basedpyright.com/latest/).
106 | - `basedpyright`: Fork of the standard `pyright` type checker. For more, see the [`basedpyright` documentation](https://docs.basedpyright.com/latest/).
107 | - `pre-commit` (optional): Ensures that several requirements are met on each commit, making it easier to maintain compliance over time. For more, see the [`pre-commit` documentation](https://pre-commit.com/).
108 |
109 | To manage and build the extension, `bpy_jupyter` uses:
110 | - `blext`: An in-development extension project manager. For more, see [`blext` repo](https://codeberg.org/so-rose/blext).
111 | - `fake-bpy-module`: Auto-generated API structure for `bpy`. For more, see [`fake-bpy-module`](https://github.com/nutti/fake-bpy-module).
112 |
113 |
114 | For documentation, we use:
115 | - `mkdocs`: Documentation generator system. For more, see the [`mkdocs` homepage](https://www.mkdocs.org/) .
116 | - `mkdocstrings[python]`: Collects high quality Python API documentation from `__doc__` strings. For more, see the [`mkdocstrings[python]`](https://mkdocstrings.github.io/python/).
117 | - `mkdocs` Plugins: Please see `uv tree` for all `mkdocs` plugins in use.
118 |
119 |
120 |
121 |
122 | ## Working with the Extension
123 | ### Running the Extension
124 | To run the local version of `bpy_jupyter` in Blender, simply execute:
125 | ```bash
126 | uv run blext run
127 | ```
128 |
129 | !!! warning
130 | `bpy_jupyter` uses the in-dev `blext` tool to build and run the extension.
131 | Being unreleased, `blext` may still have some bugs, platform-specific or otherwise.
132 |
133 |
134 |
135 | ### Building the Extension
136 | To build platform-specific extension `.zip`s, simply execute:
137 | ```bash
138 | uv run blext build
139 | ```
140 |
141 | The extension `.zip`s will be available in the newly-created `build/` directory.
142 | They can be drag-and-drop'ed into Blender for installation.
143 |
144 |
145 | ## Common Tasks
146 | ### Making a Commit
147 | As noted in [Policies -> Versioning](./policies/versioning.md), `bpy_jupyter` uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
148 |
149 | The easiest way to comply with this is to use `commitizen`:
150 | ```bash
151 | cz c
152 | ## Follow the instructions!
153 | ```
154 |
155 | !!! note
156 | Regardless of the global `commitizen` settings, running `cz c` in the repository will always respect the configuration defined in `pyproject.toml`.
157 |
158 | ### Previewing the Documentation
159 | To preview the `docs/` documentation, execute:
160 | ```bash
161 | uv run mkdocs serve
162 | ```
163 |
164 | Then, navigate to `http://127.0.0.1:8000`.
165 |
166 | !!! note
167 | This preview supports "hot-reload", which means that whenever you edit a `.md` file in `docs/`, the website will instantly update!
168 |
169 | ### Running a Linter
170 | To run the `ruff` linter, execute:
171 | ```bash
172 | uv run ruff check
173 | ```
174 |
175 | To format all files, execute:
176 | ```bash
177 | uv run ruff format
178 | ```
179 |
180 | To run the `basedpyright` type checker, execute:
181 | ```bash
182 | uv run basedpyright
183 | ```
184 |
185 | Finally, to run all tools and checks, you can always just run:
186 | ```bash
187 | uv run pre-commit run --all-files
188 | ```
189 |
--------------------------------------------------------------------------------
/docs/reference/policies/licensing.md:
--------------------------------------------------------------------------------
1 | # Licensing
2 | !!! abstract "Disclaimer"
3 | We are not lawyers, and a such, everything written here might be hogwash.
4 |
5 | If in doubt, please refer to the `LICENSE` file in the repository root and/or your own legal council.
6 |
7 | `bpy_jupyter` is distributed under the [AGPL](https://www.gnu.org/licenses/agpl-3.0.html) software license, and has **absolutely no warranty**.
8 |
9 | !!! question "Does `bpy_jupyter` come with a warranty or other support?"
10 | `bpy_jupyter` has **absolutely no warranty**, nor any guarantee of support.
11 |
12 | If you wish to arrange for commercial support, ex. in the form of workshops or specific featuers, please contact the authors/maintainers.
13 | We would be more than happy to work out a fair solution.
14 |
15 | !!! question "My organization prohibits the AGPL! What do I do?"
16 | **If the license is stopping you** from using `bpy_jupyter`, then **tell us** via email / an Issue!
17 |
18 | We're confident that we can work out a fair solution that allows you to use `bpy_jupyter`.
19 |
20 |
21 |
22 |
23 |
24 | ## Why AGPL?
25 | The AGPL guarantees your right to use, modify, fork, redistribute, **or even sell `bpy_jupyter`**, in whole or in part.
26 | The AGPL also guarantees your right to ask for the source code. [^1]
27 |
28 | [^1]: For convenience, you can find the source code here: .
29 |
30 | What's the catch?
31 | If you **give someone** `bpy_jupyter`, _including via a network service_, then you **must extend the same rights** as you yourself were given by applying a compatible license.
32 |
33 | We think that's pretty fair.
34 |
35 | !!! question "Can I copy code from `bpy_jupyter` / link to `bpy_jupyter` from other projects?"
36 | **Absolutely** - so long as you extend the same freedoms you were given by `bpy_jupyter`.
37 |
38 | In practice, the license of that "other project" must be compatible with the AGPL license of `bpy_jupyter`, since it is now a "derivative work".
39 |
40 | For example, the following (non-exclusive) kinds of projects that use `bpy_jupyter` would be required to have a license compatible with the AGPL:
41 |
42 | - A web service that uses `bpy_jupyter` to sell a "Jupyter in Blender" service.
43 | - An extension that copied a function from `bpy_jupyter`, to provide its own functionality.
44 |
45 | !!! question "Do I have to make internal `bpy_jupyter`-based tools public?"
46 | **Absolutely not**.
47 | The AGPL only applies on _distribution_.
48 |
49 | If you don't give your `bpy_jupyter`-based tool to third partiers, then no third party may claim any AGPL-protected rights to `bpy_jupyter`.
50 |
51 | !!! question "Are the dependencies of `bpy_jupyter` also AGPL?"
52 | **Absolutely not**, since that's not our code!
53 |
54 | Please refer to the relevant dependencies for license details.
55 |
56 | !!! question "Can I really sell `bpy_jupyter`?"
57 | **Absolutely!**
58 |
59 | So long as you adhere to the terms of the license, including ex. granting users access to the source code (including modifications), you are free to sell `bpy_jupyter`.
60 |
61 | We consider this ability to be a fundamental _software freedom_.
62 |
--------------------------------------------------------------------------------
/docs/reference/policies/versioning.md:
--------------------------------------------------------------------------------
1 | # Versioning
2 | `bpy_jupyter` follows [semantic versioning](https://semver.org/).
3 |
4 | !!! example
5 | We **would not** consider the following to be "breaking changes":
6 |
7 | - Adding support for a new version of Blender.
8 | - Changes to "private" parts of the extension not intended to be accessed by users, by GUI, script, or otherwise.
9 | - Changes to the build process and/or documentation.
10 |
11 | We **would** consider the following to be "breaking changes" to be:
12 |
13 | - Removing support for an old version of Blender.
14 | - Any change to a part of the extension that might be used via scripting.
15 | - Any change to the extension UI that removes the user's ability to do something.
16 |
17 |
18 |
19 | ## Blender Version Support
20 | Each version of `bpy_jupyter` explicitly supports a particular subset of Blender versions, including **all** dependencies vendored by those Blender versions.
21 |
22 | Please see `pyproject.toml` for a precise list.
23 |
24 |
25 |
26 | ## Jupyter Message Specification Version Support
27 | The [Jupyter Message Specification](https://jupyter-client.readthedocs.io/en/latest/messaging.html) defines how Jupyter frontends communicate with Jupyter kernels.
28 | This specification is versioned independently from any particular frontend ex. `jupyter_client`.
29 |
30 | To determine the specification supported by `bpy_jupyter`, please refer to the fixed version of `ipykernel` defined in the project's `pyproject.toml`.
31 |
32 |
33 |
34 | ## Commit Messages
35 | `bpy_jupyter` follows the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) standard for commit messages.
36 |
37 | Additionally, it is presumed that the `commitizen` utility is used to author commits, manipulate the extension version, and generate `CHANGELOG.md`, as defined in `pyproject.toml`.
38 |
--------------------------------------------------------------------------------
/docs/reference/python_api/bpy_jupyter.md:
--------------------------------------------------------------------------------
1 | # `bpy_jupyter`
2 |
3 | ::: bpy_jupyter
4 |
5 | ---
6 |
7 | ::: bpy_jupyter.preferences
8 |
9 | ---
10 |
11 | ::: bpy_jupyter.types
12 |
--------------------------------------------------------------------------------
/docs/reference/python_api/bpy_jupyter_operators.md:
--------------------------------------------------------------------------------
1 | # `bpy_jupyter.operators`
2 |
3 | ::: bpy_jupyter.operators
4 |
5 | ---
6 |
7 | ::: bpy_jupyter.operators.copy_kern_info_to_clipboard
8 |
9 | ---
10 |
11 | ::: bpy_jupyter.operators.start_jupyter_kernel
12 |
13 | ---
14 |
15 | ::: bpy_jupyter.operators.stop_jupyter_kernel
16 |
--------------------------------------------------------------------------------
/docs/reference/python_api/bpy_jupyter_panels.md:
--------------------------------------------------------------------------------
1 | # `bpy_jupyter.panels`
2 |
3 | ::: bpy_jupyter.panels
4 |
5 | ---
6 |
7 | ::: bpy_jupyter.panels.jupyter_panel
8 |
--------------------------------------------------------------------------------
/docs/reference/python_api/bpy_jupyter_services.md:
--------------------------------------------------------------------------------
1 | # `bpy_jupyter.services`
2 |
3 | ::: bpy_jupyter.services
4 |
5 | ---
6 |
7 | ::: bpy_jupyter.services.async_event_loop
8 |
9 | ---
10 |
11 | ::: bpy_jupyter.services.jupyter_kernel
12 |
13 | ---
14 |
15 | ::: bpy_jupyter.registration
16 |
--------------------------------------------------------------------------------
/docs/reference/python_api/bpy_jupyter_utils.md:
--------------------------------------------------------------------------------
1 | # `bpy_jupyter.utils`
2 |
3 | ::: bpy_jupyter.utils
4 |
5 | ---
6 |
7 | ::: bpy_jupyter.utils.ipykernel
8 |
--------------------------------------------------------------------------------
/docs/reference/release_notes.md:
--------------------------------------------------------------------------------
1 | ../../CHANGELOG.md
--------------------------------------------------------------------------------
/docs/user_guides/getting_started.md:
--------------------------------------------------------------------------------
1 | !!! abstract
2 | Get going quickly with `bpy_jupyter`!
3 |
4 | **Still need to install `bpy_jupyter`?** See [Installation](../installation.md).
5 |
6 | # Getting Started
7 | !!! warning "Warning: `uv` Required"
8 | It is **strongly suggested** to install [`uv`](https://docs.astral.sh/uv/) before following this guide, using the [`uv` installation guide](https://docs.astral.sh/uv/getting-started/installation/).
9 |
10 | This is to make use of the `ucx``uv` ships with the `uvx` command, which makes it easy to run Python program without prior installation:
11 |
12 | ```bash
13 | $ uvx ruff
14 | Ruff: An extremely fast Python linter and code formatter.
15 |
16 | Usage: ruff [OPTIONS]
17 | ...
18 | ```
19 |
20 | _If you don't want to use `uv`, feel free to substitute `uvx ` for your preferred method of running ``._
21 |
22 | ## Starting a Jupyter Kernel
23 | After installing the extension, navigate to `Properties -> Scene`:
24 |
25 | { loading=lazy, width=300 }
26 | /// caption
27 | Default Extension Panel
28 | ///
29 |
30 | To run the kernel, follow these steps:
31 |
32 | 1. Press the `Start Kernel` button.
33 | 2. Press the `Kernel Connection File -> (Copy) File Path` button.
34 |
35 | That's it!
36 | You can now use `jupyer-console` to connect to Blender's running kernel, simply by pasting the connection file path after `--existing`:
37 |
38 | ```bash
39 | $ uvx jupyter-console --existing path/to/connection.json
40 | Jupyter console 6.6.3
41 |
42 | Python 3.11.9 (main, Sep 11 2024, 06:43:20) [GCC 11.2.1 20220127 (Red Hat 11.2.1-9)]
43 | Type 'copyright', 'credits' or 'license' for more information
44 | IPython 9.2.0 -- An enhanced Interactive Python. Type '?' for help.
45 | Tip: Use `ipython --help-all | less` to view all the IPython configuration options.
46 |
47 | In [1]:
48 | ```
49 |
50 | !!! warning "Warning: `bpy_jupyter` Requires Online Access"
51 | { loading=lazy, width=300, align=right }
52 |
53 | If your panel looks like this, then your distribution of Blender doesn't (currently) allow online access!
54 |
55 | A running Jupyter kernel creates and listens to network ports, which may be accessible from unexpected places.
56 | Anybody capable of connecting to these ports may also capable of _arbitrary code execution_ on your computer.
57 |
58 | For this reason, `Preferences -> System -> Allow Online Access` must be checked in order to start a Jupyter kernel.
59 |
60 | !!! danger
61 | **Always check** your OS / firewall settings before starting a kernel.
62 | Failure to correctly prohibit external connections to kernel ports may allow an attacker to execute arbitrary code on your computer.
63 |
64 | It is the responsibility of your system administrator to prevent malicious third-parties from being able to access the network ports opened by `bpy_jupyter`.
65 |
66 |
67 |
68 | ### Using a Jupyter Kernel
69 |
70 | !!! warning "Under Construction"
71 | This section is incomplete.
72 |
73 | For now, we suggest browsing the [`bpy` Gallery](https://kolibril13.github.io/bpy-gallery/).
74 |
75 | At this point, one may `import bpy` and enjoy the full power of Blender's Python API.
76 | To illustrate this, several concrete examples follow!
77 |
78 | !!! example "Example: Moving the Default Cube"
79 | The first thing you might want to try is moving the default cube!
80 | ```ipython
81 | In [1]: import bpy
82 |
83 | In [2]: bpy.context.object
84 | Out[2]: bpy.data.objects['Cube']
85 |
86 | In [3]: bpy.context.object.location.z
87 | Out[3]: 0.0
88 |
89 | In [4]: bpy.context.object.location.z = 2 ## You should see this in Blender!
90 |
91 | In [5]: bpy.context.object.location.z
92 | Out[5]: 2.0
93 | ```
94 |
95 | !!! reference
96 | For more examples, see the [`bpy` Gallery](https://kolibril13.github.io/bpy-gallery/).
97 |
--------------------------------------------------------------------------------
/docs/user_guides/images/panel_active.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Octoframes/bpy_jupyter/ccaaeb15ab9cf4217becd5f1d68c35a70d77e4a9/docs/user_guides/images/panel_active.png
--------------------------------------------------------------------------------
/docs/user_guides/images/panel_default.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Octoframes/bpy_jupyter/ccaaeb15ab9cf4217becd5f1d68c35a70d77e4a9/docs/user_guides/images/panel_default.png
--------------------------------------------------------------------------------
/docs/user_guides/images/panel_offline.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Octoframes/bpy_jupyter/ccaaeb15ab9cf4217becd5f1d68c35a70d77e4a9/docs/user_guides/images/panel_offline.png
--------------------------------------------------------------------------------
/mkdocs.yml:
--------------------------------------------------------------------------------
1 | site_name: bpy_jupyter
2 |
3 | nav:
4 | - Overview: index.md
5 | - installation.md
6 | - User Guides:
7 | - Getting Started: user_guides/getting_started.md
8 | #- Resources:
9 | # - resources/extension_resources.md
10 | # - resources/git_resources.md
11 | - Reference:
12 | - Release Notes: reference/release_notes.md
13 | - reference/contributing.md
14 | - Policies:
15 | - reference/policies/versioning.md
16 | - reference/policies/licensing.md
17 | # - reference/policies/contributing.md
18 | # - reference/policies/schemas.md
19 | - Python API:
20 | - reference/python_api/bpy_jupyter.md
21 | - reference/python_api/bpy_jupyter_operators.md
22 | - reference/python_api/bpy_jupyter_panels.md
23 | - reference/python_api/bpy_jupyter_services.md
24 | - reference/python_api/bpy_jupyter_utils.md
25 |
26 | markdown_extensions:
27 | - attr_list
28 | - md_in_html
29 | - pymdownx.blocks.caption
30 | - admonition
31 | - pymdownx.superfences
32 | - footnotes
33 | - pymdownx.tabbed:
34 | alternate_style: true
35 | - pymdownx.emoji:
36 | emoji_index: !!python/name:material.extensions.emoji.twemoji
37 | emoji_generator: !!python/name:material.extensions.emoji.to_svg
38 |
39 | theme:
40 | language: en
41 | name: "material"
42 | palette:
43 | scheme: slate
44 | primary: purple
45 | accent: orange
46 | features:
47 | - navigation.sections
48 | - content.tabs.link
49 |
50 | plugins:
51 | - termynal
52 | - search
53 | - autorefs
54 | - privacy
55 | - offline
56 | - gh-admonitions
57 | - macros
58 |
59 | - mkdocstrings:
60 | handlers:
61 | python:
62 | options:
63 | allow_inspection: true
64 | parameter_headings: false
65 | show_root_heading: true
66 | group_by_category: true
67 | show_category_heading: false
68 | show_symbol_type_heading: true
69 | show_symbol_type_toc: true
70 | docstring_style: google
71 | merge_init_into_class: true
72 | separate_signature: true
73 | show_signature_annotations: true
74 | show_overloads: true
75 | signature_crossrefs: true
76 | unwrap_annotated: true
77 | docstring_section_style: spacy
78 | extensions:
79 | - griffe_pydantic:
80 | schema: true
81 | inventories:
82 | - https://installer.readthedocs.io/en/stable/objects.inv
83 |
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
1 | [project]
2 | name = "bpy_jupyter"
3 | version = "0.3.0"
4 | description = "Embeds a Jupyter kernel within Blender"
5 | authors = [
6 | { name = "Sofus Albert Høgsbro Rose", email = "bpyjupyter@sofusrose.com" },
7 | ]
8 | maintainers = [
9 | { name = "Sofus Albert Høgsbro Rose", email = "bpyjupyter@sofusrose.com" },
10 | { name = "Jan-Hendrik Mueller", email = "bpyjupyter@sofusrose.com" },
11 | ]
12 | readme = "README.md"
13 | requires-python = "~= 3.11"
14 | license = "AGPL-3.0-or-later"
15 | dependencies = [
16 | "ipykernel==6.29.5",
17 | "pydantic>=2.9.2",
18 | "pyperclipfix>=1.9.4",
19 | ]
20 |
21 | [project.urls]
22 | Homepage = "https://kolibril13.github.io/bpy-gallery/"
23 |
24 | ####################
25 | # - Blender Extension
26 | ####################
27 | [project.optional-dependencies]
28 | blender4_3 = [
29 | "autopep8==2.3.1", # # ⭳⭳⭳ MANAGED BY BLEXT ⭳⭳⭳
30 | "certifi==2021.10.8",
31 | "charset_normalizer==2.0.10",
32 | "cython==0.29.30",
33 | "idna==3.3",
34 | "numpy==1.24.3",
35 | "pip==24.0",
36 | "pycodestyle==2.12.1",
37 | "requests==2.27.1",
38 | "setuptools==63.2.0",
39 | "urllib3==1.26.8",
40 | "zstandard==0.16.0", # # ⭱⭱⭱ MANAGED BY BLEXT ⭱⭱⭱
41 | ]
42 | blender4_4 = [
43 | "autopep8==2.3.1", # # ⭳⭳⭳ MANAGED BY BLEXT ⭳⭳⭳
44 | "certifi==2021.10.8",
45 | "charset_normalizer==2.0.10",
46 | "cython==0.29.30",
47 | "idna==3.3",
48 | "numpy==1.24.3",
49 | "pip==24.0",
50 | "pycodestyle==2.12.1",
51 | "requests==2.27.1",
52 | "setuptools==63.2.0",
53 | "urllib3==1.26.8",
54 | "zstandard==0.16.0", # # ⭱⭱⭱ MANAGED BY BLEXT ⭱⭱⭱
55 | ]
56 |
57 | [tool.blext]
58 | pretty_name = "bpy Jupyter"
59 | blender_version_min = '4.3.0'
60 | blender_version_max = '4.5.0'
61 | bl_tags = ["Development", "Import-Export", "Pipeline", "System"]
62 | copyright = ["2025 bpy_jupyter Contributors"]
63 |
64 | supported_platforms = [
65 | 'linux-x64',
66 | 'macos-x64',
67 | 'macos-arm64',
68 | 'windows-x64',
69 | ]
70 |
71 | [tool.blext.permissions]
72 | files = 'Create, delete Jupyter kernel connection file'
73 | network = 'Expose Jupyter kernel sockets'
74 | clipboard = 'Copy Jupyter kernel information to the clipboard'
75 |
76 | ####################
77 | # - Blender Extension
78 | ####################
79 | [tool.uv]
80 | managed = true
81 | package = false
82 | dev-dependencies = [
83 | "pytest>=8.3.5",
84 | "pytest-cov>=6.1.1",
85 | "ruff>=0.11.8",
86 | "basedpyright>=1.29.1",
87 | "blext",
88 | "fake-bpy-module>=20250505",
89 | "griffe-pydantic>=1.1.4",
90 | "mkdocs>=1.6.1",
91 | "mkdocs-github-admonitions-plugin>=0.0.3",
92 | "mkdocs-macros-plugin>=1.3.7",
93 | "mkdocs-material>=9.6.12",
94 | "mkdocstrings[python]>=0.29.1",
95 | "termynal>=0.13.0",
96 | ]
97 | conflicts = [
98 | [
99 | {extra = "blender4_3"}, # # ⭳⭳⭳ MANAGED BY BLEXT ⭳⭳⭳
100 | {extra = "blender4_4"}, # # ⭱⭱⭱ MANAGED BY BLEXT ⭱⭱⭱
101 | ],
102 | ]
103 |
104 | [tool.uv.sources]
105 | blext = { git = "https://codeberg.org/so-rose/blext.git" }
106 |
107 | ####################
108 | # - Tooling: Ruff
109 | ####################
110 | [tool.ruff]
111 | target-version = "py311"
112 | line-length = 88
113 |
114 | [tool.ruff.lint]
115 | task-tags = ["TODO"]
116 | select = [
117 | "E", # pycodestyle ## General Purpose
118 | "F", # pyflakes ## General Purpose
119 | "PL", # Pylint ## General Purpose
120 |
121 | ## Code Quality
122 | "TCH", # flake8-type-checking ## Type Checking Block Validator
123 | "C90", # mccabe ## Avoid Too-Complex Functions
124 | "ERA", # eradicate ## Ban Commented Code
125 | "TRY", # tryceratops ## Exception Handling Style
126 | "B", # flake8-bugbear ## Opinionated, Probable-Bug Patterns
127 | "N", # pep8-naming
128 | "D", # pydocstyle
129 | "SIM", # flake8-simplify ## Sanity-Check for Code Simplification
130 | "SLF", # flake8-self ## Ban Private Member Access
131 | "RUF", # Ruff-specific rules ## Extra Good-To-Have Rules
132 |
133 | ## Style
134 | "I", # isort ## Force import Sorting
135 | "UP", # pyupgrade ## Enforce Upgrade to Newer Python Syntaxes
136 | "COM", # flake8-commas ## Enforce Trailing Commas
137 | "Q", # flake8-quotes ## Finally - Quoting Style!
138 | "PTH", # flake8-use-pathlib ## Enforce pathlib usage
139 | "A", # flake8-builtins ## Prevent Builtin Shadowing
140 | "C4", # flake9-comprehensions ## Check Compehension Appropriateness
141 | "DTZ", # flake8-datetimez ## Ban naive Datetime Creation
142 | "EM", # flake8-errmsg ## Check Exception String Formatting
143 | "ISC", # flake8-implicit-str-concat ## Enforce Good String Literal Concat
144 | "G", # flake8-logging-format ## Enforce Good Logging Practices
145 | "INP", # flake8-no-pep420 ## Ban PEP420; Enforce __init__.py.
146 | "PIE", # flake8-pie ## Misc Opinionated Checks
147 | "T20", # flake8-print ## Ban print()
148 | "RSE", # flake8-raise ## Check Niche Exception Raising Pattern
149 | "RET", # flake8-return ## Enforce Good Returning
150 | "ARG", # flake8-unused-arguments ## Ban Unused Arguments
151 |
152 | # Specific
153 | "PT", # flake8-pytest-style ## pytest-Specific Checks
154 | ]
155 | ignore = [
156 | "COM812", # Conflicts w/Formatter
157 | "ISC001", # Conflicts w/Formatter
158 | "Q000", # Conflicts w/Formatter
159 | "Q001", # Conflicts w/Formatter
160 | "Q002", # Conflicts w/Formatter
161 | "Q003", # Conflicts w/Formatter
162 | "D206", # Conflicts w/Formatter
163 | "E701", # class foo(Parent): pass or if simple: return are perfectly elegant
164 | "ERA001", # 'Commented-out code' seems to be just about anything to ruff
165 | "RUF001", # We use a lot of unicode, yes, on purpose!
166 |
167 | # Line Length - Controversy Incoming
168 | ## Hot Take: Let the Formatter Worry about Line Length
169 | ## - Yes dear reader, I'm with you. Soft wrap can go too far.
170 | ## - ...but also, sometimes there are real good reasons not to split.
171 | ## - Ex. I think 'one sentence per line' docstrings are a valid thing.
172 | ## - Overlong lines tend to be be a code smell anyway
173 | ## - We'll see if my hot takes survive the week :)
174 | "E501", # Let Formatter Worry about Line Length
175 | ]
176 |
177 | ####################
178 | # - Tooling: Ruff Sublinters
179 | ####################
180 | [tool.ruff.lint.flake8-bugbear]
181 | extend-immutable-calls = []
182 |
183 | [tool.ruff.lint.pycodestyle]
184 | max-doc-length = 88
185 | ignore-overlong-task-comments = true
186 |
187 | [tool.ruff.lint.pydocstyle]
188 | convention = "google"
189 |
190 | [tool.ruff.lint.pylint]
191 | max-args = 6
192 |
193 | ####################
194 | # - Tooling: Ruff Formatter
195 | ####################
196 | [tool.ruff.format]
197 | preview = true
198 | quote-style = "single"
199 | indent-style = "tab"
200 | docstring-code-format = false
201 |
202 |
203 | ####################
204 | # - Tool: basedpyright
205 | ####################
206 | [tool.basedpyright]
207 | defineConstant = { DEBUG = true }
208 |
209 | include = ["bpy_jupyter"]
210 |
211 | reportMissingImports = "error"
212 | reportMissingTypeStubs = true
213 |
214 | reportAny = false ## fake-bpy-module is not friends with this.
215 | reportUnknownMemberType = false ## Nor with this!
216 |
217 | executionEnvironments = [
218 | { root = ".", pythonVersion = "3.11", extraPaths = [ ".venv/lib/python3.11/site-packages" ] },
219 | ]
220 |
221 | ####################
222 | # - Tooling: pytest
223 | ####################
224 | [tool.pytest.ini_options]
225 | testpaths = ["tests"]
226 |
227 |
228 | ####################
229 | # - Tooling: Commits
230 | ####################
231 | [tool.commitizen]
232 | name = "cz_gitmoji"
233 | version_scheme = "semver2"
234 | version_provider = "uv"
235 | tag_format = "v$version"
236 |
237 | # Files
238 | changelog_file = "CHANGELOG.md"
239 |
240 | # Version Bumping
241 | retry_after_failure = true
242 | major_version_zero = true
243 | update_changelog_on_bump = true
244 |
245 | # Annotations / Signature
246 | gpg_sign = true
247 | annotated_tag = true
248 |
--------------------------------------------------------------------------------