ipython-icat 0.2.2__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,16 +1,17 @@
1
- Metadata-Version: 2.1
1
+ Metadata-Version: 2.4
2
2
  Name: ipython-icat
3
- Version: 0.2.2
3
+ Version: 0.3.0
4
4
  Summary: IPython magic command for displaying images in kitty terminal
5
5
  Author-email: Tony Kabilan Okeke <tonykabilanokeke@gmail.com>
6
6
  Project-URL: Homepage, https://github.com/Kabilan108/ipython-icat
7
- Keywords: ipython,magic,image,display,kitty,icat
7
+ Keywords: ipython,magic,image,display,kitty,icat,ipython extension,ghostty
8
8
  Requires-Python: >=3.9
9
9
  Description-Content-Type: text/markdown
10
10
  License-File: LICENSE.md
11
11
  Requires-Dist: ipython
12
12
  Requires-Dist: matplotlib
13
13
  Requires-Dist: pillow
14
+ Dynamic: license-file
14
15
 
15
16
  # ipython-icat
16
17
 
@@ -30,7 +31,7 @@ pip install ipython-icat
30
31
  - IPython
31
32
  - matplotlib
32
33
  - Pillow (PIL)
33
- - kitty terminal
34
+ - terminal emulator with support for kitty graphics protocol (KGP) e.g., kitty, ghostty
34
35
 
35
36
  ## Usage
36
37
 
@@ -52,6 +53,35 @@ To use the kitty backend for matplotlib:
52
53
 
53
54
  After running this command, any matplotlib plots you create will be displayed directly in your kitty terminal.
54
55
 
56
+ ### Use as a Default Backend
57
+
58
+ To set the kitty backend for matplotlib as the default, add the following lines to your IPython configuration file:
59
+
60
+ 1. `c.InteractiveShellApp.extensions = ['icat']`
61
+ 2. `c.InteractiveShellApp.exec_lines = ['%plt_icat']`
62
+
63
+ #### Automatic Setup
64
+
65
+ You can quickly set up IPython to use the icat extension using the setup command:
66
+
67
+ ```bash
68
+ python -m icat setup
69
+ ```
70
+
71
+ This command will:
72
+ 1. Create an IPython profile if it doesn't exist (or use an existing one)
73
+ 2. Configure the profile to load the icat extension automatically
74
+ 3. Set matplotlib to use the icat backend by default
75
+
76
+ Additional options:
77
+ - `--profile NAME` - Use a specific profile instead of the default
78
+ - `--ipython-path PATH` - Specify a custom path to the .ipython directory
79
+
80
+ Example with custom profile:
81
+ ```bash
82
+ python -m icat setup --profile myprofile
83
+ ```
84
+
55
85
  ### Displaying Images
56
86
 
57
87
  To display an image file or a PIL Image object:
@@ -74,6 +104,10 @@ You can also resize the image when displaying:
74
104
  %icat path/to/your/image.jpg -w 300 -h 200
75
105
  ```
76
106
 
107
+ ### Using Ghostty
108
+
109
+ If you'd like to use this plugin with Ghostty, make sure to install the [static kitten binary](https://github.com/kovidgoyal/kitty/releases) which will allow you to run `kitten icat`.
110
+
77
111
  ## Features
78
112
 
79
113
  - Display matplotlib plots directly in kitty terminal
@@ -85,17 +119,12 @@ You can also resize the image when displaying:
85
119
 
86
120
  Contributions are welcome! Please feel free to submit a Pull Request.
87
121
 
88
- ## License
89
-
90
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
91
-
92
122
  ## Acknowledgments
93
123
 
94
124
  - [matplotlib-backend-kitty](https://github.com/jktr/matplotlib-backend-kitty) for the original implementation
95
125
  - [matplotlib](https://github.com/matplotlib/matplotlib) and [Pillow](https://python-pillow.org/) for their excellent libraries
96
- - [kitty terminal](https://github.com/kovidgoyal/kitty) for supporting image protocol
97
-
98
- ## Contact
126
+ - [kitty terminal](https://github.com/kovidgoyal/kitty) for developing the graphics protocol
99
127
 
100
- If you have any questions or feedback, please open an issue on the GitHub repository.
128
+ ## License
101
129
 
130
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
@@ -16,7 +16,7 @@ pip install ipython-icat
16
16
  - IPython
17
17
  - matplotlib
18
18
  - Pillow (PIL)
19
- - kitty terminal
19
+ - terminal emulator with support for kitty graphics protocol (KGP) e.g., kitty, ghostty
20
20
 
21
21
  ## Usage
22
22
 
@@ -38,6 +38,35 @@ To use the kitty backend for matplotlib:
38
38
 
39
39
  After running this command, any matplotlib plots you create will be displayed directly in your kitty terminal.
40
40
 
41
+ ### Use as a Default Backend
42
+
43
+ To set the kitty backend for matplotlib as the default, add the following lines to your IPython configuration file:
44
+
45
+ 1. `c.InteractiveShellApp.extensions = ['icat']`
46
+ 2. `c.InteractiveShellApp.exec_lines = ['%plt_icat']`
47
+
48
+ #### Automatic Setup
49
+
50
+ You can quickly set up IPython to use the icat extension using the setup command:
51
+
52
+ ```bash
53
+ python -m icat setup
54
+ ```
55
+
56
+ This command will:
57
+ 1. Create an IPython profile if it doesn't exist (or use an existing one)
58
+ 2. Configure the profile to load the icat extension automatically
59
+ 3. Set matplotlib to use the icat backend by default
60
+
61
+ Additional options:
62
+ - `--profile NAME` - Use a specific profile instead of the default
63
+ - `--ipython-path PATH` - Specify a custom path to the .ipython directory
64
+
65
+ Example with custom profile:
66
+ ```bash
67
+ python -m icat setup --profile myprofile
68
+ ```
69
+
41
70
  ### Displaying Images
42
71
 
43
72
  To display an image file or a PIL Image object:
@@ -60,6 +89,10 @@ You can also resize the image when displaying:
60
89
  %icat path/to/your/image.jpg -w 300 -h 200
61
90
  ```
62
91
 
92
+ ### Using Ghostty
93
+
94
+ If you'd like to use this plugin with Ghostty, make sure to install the [static kitten binary](https://github.com/kovidgoyal/kitty/releases) which will allow you to run `kitten icat`.
95
+
63
96
  ## Features
64
97
 
65
98
  - Display matplotlib plots directly in kitty terminal
@@ -71,17 +104,12 @@ You can also resize the image when displaying:
71
104
 
72
105
  Contributions are welcome! Please feel free to submit a Pull Request.
73
106
 
74
- ## License
75
-
76
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
77
-
78
107
  ## Acknowledgments
79
108
 
80
109
  - [matplotlib-backend-kitty](https://github.com/jktr/matplotlib-backend-kitty) for the original implementation
81
110
  - [matplotlib](https://github.com/matplotlib/matplotlib) and [Pillow](https://python-pillow.org/) for their excellent libraries
82
- - [kitty terminal](https://github.com/kovidgoyal/kitty) for supporting image protocol
83
-
84
- ## Contact
111
+ - [kitty terminal](https://github.com/kovidgoyal/kitty) for developing the graphics protocol
85
112
 
86
- If you have any questions or feedback, please open an issue on the GitHub repository.
113
+ ## License
87
114
 
115
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
@@ -1,21 +1,20 @@
1
1
  # modified from https://github.com/jktr/matplotlib-backend-kitty
2
2
 
3
- from IPython.core.magic_arguments import argument, magic_arguments, parse_argstring
4
- from IPython.core.magic import Magics, magics_class, line_magic
5
-
6
- from subprocess import run
7
- from io import BytesIO
8
3
  import sys
9
- import os
4
+ from io import BytesIO
5
+ from pathlib import Path
6
+ from subprocess import run
10
7
 
11
- from matplotlib.backend_bases import _Backend, FigureManagerBase
12
- from matplotlib.backends.backend_agg import FigureCanvasAgg
8
+ import matplotlib
9
+ from IPython.core.magic import Magics, line_magic, magics_class
10
+ from IPython.core.magic_arguments import argument, magic_arguments, parse_argstring
13
11
  from matplotlib import interactive, is_interactive
14
12
  from matplotlib._pylab_helpers import Gcf
15
- import matplotlib
16
-
13
+ from matplotlib.backend_bases import FigureManagerBase, _Backend
14
+ from matplotlib.backends.backend_agg import FigureCanvasAgg
17
15
  from PIL import Image
18
16
 
17
+
19
18
  if hasattr(sys, "ps1") or sys.flags.interactive:
20
19
  interactive(True)
21
20
 
@@ -32,7 +31,7 @@ def _run(*cmd):
32
31
  return f
33
32
 
34
33
 
35
- _icat = _run("kitty", "+kitten", "icat", "--align", "left")
34
+ _icat = _run("kitten", "icat", "--align", "left")
36
35
 
37
36
 
38
37
  class FigureManagerICat(FigureManagerBase):
@@ -84,7 +83,7 @@ class ICatMagics(Magics):
84
83
  user_ns = self.shell.user_ns
85
84
  if image_arg in user_ns and isinstance(user_ns[image_arg], Image.Image):
86
85
  img = user_ns[image_arg]
87
- elif os.path.isfile(image_arg):
86
+ elif Path(image_arg).is_file():
88
87
  img = Image.open(image_arg)
89
88
  else:
90
89
  print(
@@ -0,0 +1,169 @@
1
+ import re
2
+ import subprocess
3
+ from pathlib import Path
4
+ from typing import List, Optional, Tuple
5
+
6
+ from traitlets.config import Config
7
+ from traitlets.config.loader import PyFileConfigLoader
8
+
9
+
10
+ def main():
11
+ import argparse
12
+ import sys
13
+
14
+ parser = argparse.ArgumentParser(description="Setup IPython with icat integration")
15
+ subparsers = parser.add_subparsers(dest="command")
16
+
17
+ setup_parser = subparsers.add_parser("setup", help="Configure IPython to use icat")
18
+ setup_parser.add_argument(
19
+ "--profile", default="default", help="IPython profile name"
20
+ )
21
+ setup_parser.add_argument(
22
+ "--ipython-path", default=None, help="Custom path to .ipython directory"
23
+ )
24
+
25
+ args = parser.parse_args()
26
+
27
+ if not args.command:
28
+ parser.print_help()
29
+ return
30
+
31
+ if args.command == "setup":
32
+ try:
33
+ success = setup_ipython_profile(args.ipython_path, args.profile)
34
+ if not success:
35
+ sys.exit(1)
36
+ except Exception as e:
37
+ print(f"Error: {e}")
38
+ sys.exit(1)
39
+ else:
40
+ parser.print_help()
41
+
42
+
43
+ def setup_ipython_profile(
44
+ ipython_path: Optional[str] = None, profile_name: str = "default"
45
+ ) -> bool:
46
+ """Update or create an IPython profile to use the icat backend."""
47
+ profile_path = get_profile_path(profile_name, ipython_path)
48
+
49
+ extensions_line, exec_lines_line = dynamic_update_config(profile_path)
50
+ lines = dynamic_update_file(profile_path, extensions_line, exec_lines_line)
51
+
52
+ try:
53
+ with profile_path.open("w") as f:
54
+ f.writelines(lines)
55
+ except IOError as e:
56
+ raise RuntimeError(f"Failed to write to config file {profile_path}: {e}")
57
+ except PermissionError:
58
+ raise RuntimeError(f"Permission denied when writing to {profile_path}")
59
+
60
+ print(f"Successfully updated IPython config at {profile_path}")
61
+ return True
62
+
63
+
64
+ def sanitize_profile_name(profile_name: str) -> str:
65
+ """Sanitize profile name to prevent command injection"""
66
+ # Allow only alphanumeric characters, dashes and underscores
67
+ if not profile_name or not re.match(r"^[a-zA-Z0-9_-]+$", profile_name):
68
+ raise ValueError(
69
+ "Profile name must contain only alphanumeric characters, underscores, or dashes"
70
+ )
71
+ return profile_name
72
+
73
+
74
+ def get_profile_path(profile_name: str, ipython_path: Optional[str] = None) -> Path:
75
+ """Silently create a default profile if it doesn't exist"""
76
+ profile_name = sanitize_profile_name(profile_name)
77
+
78
+ try:
79
+ if ipython_path is None:
80
+ ipython_path = Path.home() / ".ipython"
81
+ else:
82
+ ipython_path = Path(ipython_path).expanduser().resolve()
83
+
84
+ if not ipython_path.exists():
85
+ raise FileNotFoundError(f"IPython path {ipython_path} does not exist")
86
+
87
+ profile_dir = ipython_path / f"profile_{profile_name}"
88
+ if not profile_dir.exists():
89
+ try:
90
+ subprocess.run(
91
+ ["ipython", "profile", "create", profile_name], check=True
92
+ )
93
+ except subprocess.CalledProcessError as e:
94
+ raise RuntimeError(f"Failed to create IPython profile: {e.stderr}")
95
+
96
+ profile_path = profile_dir / "ipython_config.py"
97
+ return profile_path
98
+ except (PermissionError, OSError) as e:
99
+ raise RuntimeError(f"Error accessing IPython paths: {e}")
100
+
101
+
102
+ def dynamic_update_config(profile_path: Path) -> Tuple[str, str]:
103
+ """Returns updated extensions and exec_lines"""
104
+ profile_path = Path(profile_path)
105
+
106
+ config = Config()
107
+ if profile_path.exists():
108
+ try:
109
+ config_loader = PyFileConfigLoader(
110
+ filename=profile_path.name, path=str(profile_path.parent)
111
+ )
112
+ config = config_loader.load_config()
113
+ except Exception as e:
114
+ raise RuntimeError(f"Error loading IPython config: {e}")
115
+
116
+ # Ensure extensions and exec_lines are lists
117
+ extensions = config.get("InteractiveShellApp", {}).get("extensions", [])
118
+ exec_lines = config.get("InteractiveShellApp", {}).get("exec_lines", [])
119
+
120
+ if "icat" not in extensions:
121
+ extensions.append("icat")
122
+
123
+ if "%plt_icat" not in exec_lines:
124
+ exec_lines.append("%plt_icat")
125
+
126
+ extensions_line = f"c.InteractiveShellApp.extensions = {extensions}\n"
127
+ exec_lines_line = f"c.InteractiveShellApp.exec_lines = {exec_lines}\n"
128
+
129
+ return extensions_line, exec_lines_line
130
+
131
+
132
+ def dynamic_update_file(
133
+ profile_path: Path, extensions_line: str, exec_lines_line: str
134
+ ) -> List[str]:
135
+ """Write updated configuration to the file"""
136
+ profile_path = Path(profile_path)
137
+
138
+ # Read and modify only the necessary lines
139
+ if profile_path.exists():
140
+ try:
141
+ with open(profile_path, "r") as f:
142
+ lines = f.readlines()
143
+ except IOError as e:
144
+ raise RuntimeError(f"Could not read config file {profile_path}: {e}")
145
+
146
+ # Modify lines if they exist; otherwise, add them
147
+ found_extensions = False
148
+ found_exec_lines = False
149
+
150
+ for i, line in enumerate(lines):
151
+ if line.startswith("c.InteractiveShellApp.extensions ="):
152
+ lines[i] = extensions_line
153
+ found_extensions = True
154
+ elif line.startswith("c.InteractiveShellApp.exec_lines ="):
155
+ lines[i] = exec_lines_line
156
+ found_exec_lines = True
157
+
158
+ if not found_extensions:
159
+ lines.append(extensions_line)
160
+ if not found_exec_lines:
161
+ lines.append(exec_lines_line)
162
+
163
+ return lines
164
+ else:
165
+ return [extensions_line, exec_lines_line]
166
+
167
+
168
+ if __name__ == "__main__":
169
+ main()
@@ -1,16 +1,17 @@
1
- Metadata-Version: 2.1
1
+ Metadata-Version: 2.4
2
2
  Name: ipython-icat
3
- Version: 0.2.2
3
+ Version: 0.3.0
4
4
  Summary: IPython magic command for displaying images in kitty terminal
5
5
  Author-email: Tony Kabilan Okeke <tonykabilanokeke@gmail.com>
6
6
  Project-URL: Homepage, https://github.com/Kabilan108/ipython-icat
7
- Keywords: ipython,magic,image,display,kitty,icat
7
+ Keywords: ipython,magic,image,display,kitty,icat,ipython extension,ghostty
8
8
  Requires-Python: >=3.9
9
9
  Description-Content-Type: text/markdown
10
10
  License-File: LICENSE.md
11
11
  Requires-Dist: ipython
12
12
  Requires-Dist: matplotlib
13
13
  Requires-Dist: pillow
14
+ Dynamic: license-file
14
15
 
15
16
  # ipython-icat
16
17
 
@@ -30,7 +31,7 @@ pip install ipython-icat
30
31
  - IPython
31
32
  - matplotlib
32
33
  - Pillow (PIL)
33
- - kitty terminal
34
+ - terminal emulator with support for kitty graphics protocol (KGP) e.g., kitty, ghostty
34
35
 
35
36
  ## Usage
36
37
 
@@ -52,6 +53,35 @@ To use the kitty backend for matplotlib:
52
53
 
53
54
  After running this command, any matplotlib plots you create will be displayed directly in your kitty terminal.
54
55
 
56
+ ### Use as a Default Backend
57
+
58
+ To set the kitty backend for matplotlib as the default, add the following lines to your IPython configuration file:
59
+
60
+ 1. `c.InteractiveShellApp.extensions = ['icat']`
61
+ 2. `c.InteractiveShellApp.exec_lines = ['%plt_icat']`
62
+
63
+ #### Automatic Setup
64
+
65
+ You can quickly set up IPython to use the icat extension using the setup command:
66
+
67
+ ```bash
68
+ python -m icat setup
69
+ ```
70
+
71
+ This command will:
72
+ 1. Create an IPython profile if it doesn't exist (or use an existing one)
73
+ 2. Configure the profile to load the icat extension automatically
74
+ 3. Set matplotlib to use the icat backend by default
75
+
76
+ Additional options:
77
+ - `--profile NAME` - Use a specific profile instead of the default
78
+ - `--ipython-path PATH` - Specify a custom path to the .ipython directory
79
+
80
+ Example with custom profile:
81
+ ```bash
82
+ python -m icat setup --profile myprofile
83
+ ```
84
+
55
85
  ### Displaying Images
56
86
 
57
87
  To display an image file or a PIL Image object:
@@ -74,6 +104,10 @@ You can also resize the image when displaying:
74
104
  %icat path/to/your/image.jpg -w 300 -h 200
75
105
  ```
76
106
 
107
+ ### Using Ghostty
108
+
109
+ If you'd like to use this plugin with Ghostty, make sure to install the [static kitten binary](https://github.com/kovidgoyal/kitty/releases) which will allow you to run `kitten icat`.
110
+
77
111
  ## Features
78
112
 
79
113
  - Display matplotlib plots directly in kitty terminal
@@ -85,17 +119,12 @@ You can also resize the image when displaying:
85
119
 
86
120
  Contributions are welcome! Please feel free to submit a Pull Request.
87
121
 
88
- ## License
89
-
90
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
91
-
92
122
  ## Acknowledgments
93
123
 
94
124
  - [matplotlib-backend-kitty](https://github.com/jktr/matplotlib-backend-kitty) for the original implementation
95
125
  - [matplotlib](https://github.com/matplotlib/matplotlib) and [Pillow](https://python-pillow.org/) for their excellent libraries
96
- - [kitty terminal](https://github.com/kovidgoyal/kitty) for supporting image protocol
97
-
98
- ## Contact
126
+ - [kitty terminal](https://github.com/kovidgoyal/kitty) for developing the graphics protocol
99
127
 
100
- If you have any questions or feedback, please open an issue on the GitHub repository.
128
+ ## License
101
129
 
130
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
@@ -2,6 +2,7 @@ LICENSE.md
2
2
  README.md
3
3
  pyproject.toml
4
4
  icat/__init__.py
5
+ icat/__main__.py
5
6
  ipython_icat.egg-info/PKG-INFO
6
7
  ipython_icat.egg-info/SOURCES.txt
7
8
  ipython_icat.egg-info/dependency_links.txt
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "ipython-icat"
3
- version = "0.2.2"
3
+ version = "0.3.0"
4
4
  description = "IPython magic command for displaying images in kitty terminal"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.9"
@@ -12,7 +12,7 @@ dependencies = [
12
12
  authors = [
13
13
  { name = "Tony Kabilan Okeke", email = "tonykabilanokeke@gmail.com" }
14
14
  ]
15
- keywords = ["ipython", "magic", "image", "display", "kitty", "icat"]
15
+ keywords = ["ipython", "magic", "image", "display", "kitty", "icat", "ipython extension", "ghostty"]
16
16
 
17
17
  [project.urls]
18
18
  Homepage = "https://github.com/Kabilan108/ipython-icat"
@@ -26,4 +26,3 @@ dev-dependencies = [
26
26
  "jupyter>=1.1.1",
27
27
  ]
28
28
  package = true
29
-
File without changes
File without changes