[unitaryHack] Add instructions to solve make docs error for Windows/3.8 users #691
Conversation
Codecov Report
@@ Coverage Diff @@
## master #691 +/- ##
=======================================
Coverage 96.96% 96.96%
=======================================
Files 42 42
Lines 2173 2173
=======================================
Hits 2107 2107
Misses 66 66 Continue to review full report at Codecov.
|
CONTRIBUTING.md
Outdated
| To prevent errors when running `make docs` and `make doctest`, Windows developers using Pythong 3.8 will also need to edit \_\_init\_\_.py in their environment's asyncio directory. | ||
| This is due to asyncio changing their default event loop beginning in Python 3.8, and the default event loop will not support Unix-style APIs used by some dependencies. | ||
| 1. Locate your environment directory (likely C:\Users\{username}\anaconda3\envs\\{your_env}), and open {env_dir}/Lib/asyncio/\_\_init\_\_.py. |
There was a problem hiding this comment.
| To prevent errors when running `make docs` and `make doctest`, Windows developers using Pythong 3.8 will also need to edit \_\_init\_\_.py in their environment's asyncio directory. | |
| This is due to asyncio changing their default event loop beginning in Python 3.8, and the default event loop will not support Unix-style APIs used by some dependencies. | |
| 1. Locate your environment directory (likely C:\Users\{username}\anaconda3\envs\\{your_env}), and open {env_dir}/Lib/asyncio/\_\_init\_\_.py. | |
| To prevent errors when running `make docs` and `make doctest`, Windows developers using Python 3.8 will also need to edit `\_\_init\_\_.py` in their environment's asyncio directory. | |
| This is due to `asyncio` changing their default event loop beginning in Python 3.8, and the default event loop will not support Unix-style APIs used by some dependencies. | |
| 1. Locate your environment directory (likely `C:\Users\{username}\anaconda3\envs\\{your_env}`), and open `{env_dir}/Lib/asyncio/\_\_init\_\_.py`. |
There was a problem hiding this comment.
I also suggest linking something about asyncio.
There was a problem hiding this comment.
Link added, and changes incorporated
| * Original Code | ||
|
|
||
| if sys.platform == 'win32': # pragma: no cover | ||
| from .windows_events import * | ||
| __all__ += windows_events.__all__ | ||
| else: | ||
| from .unix_events import * # pragma: no cover | ||
| __all__ += unix_events.__all__ | ||
|
|
||
| * Replacement Code | ||
|
|
||
| if sys.platform == 'win32': # pragma: no cover | ||
| from .windows_events import * | ||
| asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy()) | ||
| __all__ += windows_events.__all__ | ||
| else: | ||
| from .unix_events import * # pragma: no cover |
There was a problem hiding this comment.
This could be done the way we format code in markdown.
There was a problem hiding this comment.
This is formatted such that is appears as a nested code block instead of a full-width code block. But if you would like it full-width instead of nested, I can change it.
There was a problem hiding this comment.
Thanks @andre-a-alves for the clear and detailed problem description / instructions. I pinged @crazy4pi314 who is on windows for review.
Did you find these instructions anywhere? Or was this a fix you came to after experimenting? I'm a bit worried about telling people they have to modify source files of asyncio in order to develop Mitiq - or at least Mitiq docs - on windows.
|
I found the fix being used in a few different places. It was an overall problem with Jupyter that has been fixed as of 6.0.3, but one of our dependencies (probably myst-nb, but I'm not positive) does not seem to have overcome the issue, yet. I am assuming it comes from Jupyter, but it could potentially come from elsewhere. Here is a GitHub link where Tornado implemented this fix, a StackExchange link that addresses this issue, and another StackExchange link that implements the same fix. I am not a fan of system-wide changes, but since this is just within a Python environment, I figured it's not too bad, especially since it only affects developers but not users. I also think the issue will eventually go away, but there's no telling when that will happen. |
|
Gotcha, thanks for the response!! With this it seems like a reasonable (temp) fix to me. |
Description
Closes #689
As described in the issue, Windows users need to edit a file in their asyncio environment which affects non-Unix-like systems running Python 3.8 or higher.
Checklist
Check off the following once complete (or if not applicable) after opening the PR. The PR will be reviewed once this checklist is complete and all tests are passing.
If some items remain, you can mark this a draft pull request.
Tips
If the validation check fails:
Run
make check-style(from the root directory of the repository) and fix any flake8 errors.Run
make formatto format your code with the black autoformatter.For more information, check the Mitiq style guidelines.
Write "Fixes #XYZ" in the description if this PR fixes Issue #XYZ.