klo-git 0.1.8__py3-none-any.whl

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.
klo/__init__.py ADDED
@@ -0,0 +1,20 @@
1
+ """
2
+ klo - Python package for garbage collection utilities and memory management.
3
+
4
+ This package provides tools and utilities for working with Python's garbage collector,
5
+ memory profiling, and cleanup operations.
6
+ """
7
+
8
+ __version__ = "0.1.8"
9
+ __author__ = "Tom Sapletta"
10
+ __email__ = "tom@example.com"
11
+
12
+ from .core import GarbageCollector, MemoryProfiler
13
+ from .utils import cleanup_temp_files, monitor_memory_usage
14
+
15
+ __all__ = [
16
+ "GarbageCollector",
17
+ "MemoryProfiler",
18
+ "cleanup_temp_files",
19
+ "monitor_memory_usage",
20
+ ]
klo/cli.py ADDED
@@ -0,0 +1,172 @@
1
+ """
2
+ CLI interface for gc package - Git Clone utility.
3
+ """
4
+
5
+ import os
6
+ import sys
7
+ import subprocess
8
+ import argparse
9
+ from pathlib import Path
10
+ from typing import Optional
11
+ import re
12
+
13
+
14
+ def parse_git_url(url: str) -> Optional[tuple]:
15
+ """
16
+ Parse git URL and extract owner and repository name.
17
+
18
+ Args:
19
+ url: Git URL (SSH or HTTPS)
20
+
21
+ Returns:
22
+ Tuple of (owner, repo) or None if invalid
23
+ """
24
+ # SSH format: git@github.com:owner/repo.git
25
+ ssh_pattern = r'git@[^:]+:([^/]+)/([^/]+)\.git$'
26
+ ssh_match = re.match(ssh_pattern, url)
27
+ if ssh_match:
28
+ return ssh_match.group(1), ssh_match.group(2)
29
+
30
+ # HTTPS format: https://github.com/owner/repo.git
31
+ https_pattern = r'https://[^/]+/([^/]+)/([^/]+)\.git$'
32
+ https_match = re.match(https_pattern, url)
33
+ if https_match:
34
+ return https_match.group(1), https_match.group(2)
35
+
36
+ # HTTPS format without .git: https://github.com/owner/repo
37
+ https_pattern_no_git = r'https://[^/]+/([^/]+)/([^/]+)$'
38
+ https_match_no_git = re.match(https_pattern_no_git, url)
39
+ if https_match_no_git:
40
+ return https_match_no_git.group(1), https_match_no_git.group(2)
41
+
42
+ return None
43
+
44
+
45
+ def create_directory_structure(owner: str, repo: str, base_path: Optional[str] = None) -> Path:
46
+ """
47
+ Create directory structure for the repository.
48
+
49
+ Args:
50
+ owner: Repository owner
51
+ repo: Repository name
52
+ base_path: Base path (defaults to ~/github)
53
+
54
+ Returns:
55
+ Path to created directory
56
+ """
57
+ if base_path is None:
58
+ base_path = os.path.expanduser("~/github")
59
+
60
+ target_dir = Path(base_path) / owner / repo
61
+ target_dir.mkdir(parents=True, exist_ok=True)
62
+
63
+ return target_dir
64
+
65
+
66
+ def clone_repository(url: str, target_dir: Path) -> bool:
67
+ """
68
+ Clone git repository to target directory.
69
+
70
+ Args:
71
+ url: Git URL to clone
72
+ target_dir: Target directory for cloning
73
+
74
+ Returns:
75
+ True if successful, False otherwise
76
+ """
77
+ try:
78
+ # Check if directory is empty
79
+ if any(target_dir.iterdir()):
80
+ print(f"Directory {target_dir} is not empty. Skipping clone.")
81
+ return False
82
+
83
+ # Clone the repository
84
+ result = subprocess.run(
85
+ ["git", "clone", url, str(target_dir)],
86
+ capture_output=True,
87
+ text=True,
88
+ check=True
89
+ )
90
+
91
+ print(f"Successfully cloned {url} to {target_dir}")
92
+ return True
93
+
94
+ except subprocess.CalledProcessError as e:
95
+ print(f"Failed to clone repository: {e}")
96
+ print(f"Error output: {e.stderr}")
97
+ return False
98
+ except FileNotFoundError:
99
+ print("Git is not installed or not in PATH")
100
+ return False
101
+
102
+
103
+ def main():
104
+ """Main CLI entry point."""
105
+ parser = argparse.ArgumentParser(
106
+ description="Git Clone utility - Clone repositories to organized directory structure",
107
+ prog="gc"
108
+ )
109
+
110
+ parser.add_argument(
111
+ "url",
112
+ help="Git repository URL (SSH or HTTPS)"
113
+ )
114
+
115
+ parser.add_argument(
116
+ "--base-path",
117
+ help="Base path for cloning (default: ~/github)",
118
+ default=None
119
+ )
120
+
121
+ parser.add_argument(
122
+ "--dry-run",
123
+ action="store_true",
124
+ help="Show what would be done without actually cloning"
125
+ )
126
+
127
+ parser.add_argument(
128
+ "--verbose",
129
+ action="store_true",
130
+ help="Verbose output"
131
+ )
132
+
133
+ args = parser.parse_args()
134
+
135
+ # Parse the URL
136
+ if args.verbose:
137
+ print(f"Parsing URL: {args.url}")
138
+
139
+ parsed = parse_git_url(args.url)
140
+ if not parsed:
141
+ print(f"Error: Invalid git URL format: {args.url}")
142
+ print("Supported formats:")
143
+ print(" SSH: git@github.com:owner/repo.git")
144
+ print(" HTTPS: https://github.com/owner/repo.git")
145
+ return
146
+
147
+ owner, repo = parsed
148
+
149
+ if args.verbose:
150
+ print(f"Owner: {owner}, Repository: {repo}")
151
+
152
+ # Create directory structure
153
+ target_dir = create_directory_structure(owner, repo, args.base_path)
154
+
155
+ if args.verbose:
156
+ print(f"Target directory: {target_dir}")
157
+
158
+ if args.dry_run:
159
+ print(f"Would clone {args.url} to {target_dir}")
160
+ return
161
+
162
+ # Clone the repository
163
+ success = clone_repository(args.url, target_dir)
164
+
165
+ if not success:
166
+ return
167
+
168
+ print(f"Repository ready at: {target_dir}")
169
+
170
+
171
+ if __name__ == "__main__":
172
+ main()
klo/core.py ADDED
@@ -0,0 +1,207 @@
1
+ """
2
+ Core garbage collection and memory management functionality.
3
+ """
4
+
5
+ import gc
6
+ import sys
7
+ import time
8
+ from typing import Dict, List, Optional, Any
9
+ import weakref
10
+
11
+
12
+ class GarbageCollector:
13
+ """Enhanced garbage collector with monitoring and control features."""
14
+
15
+ def __init__(self):
16
+ self.stats_history = []
17
+ self.enabled = gc.isenabled()
18
+
19
+ def enable(self) -> None:
20
+ """Enable garbage collection."""
21
+ gc.enable()
22
+ self.enabled = True
23
+
24
+ def disable(self) -> None:
25
+ """Disable garbage collection."""
26
+ gc.disable()
27
+ self.enabled = False
28
+
29
+ def collect(self, generation: int = 2) -> int:
30
+ """
31
+ Force garbage collection for a specific generation.
32
+
33
+ Args:
34
+ generation: Generation number (0, 1, or 2)
35
+
36
+ Returns:
37
+ Number of objects collected
38
+ """
39
+ collected = gc.collect()
40
+ self._record_stats()
41
+ return collected
42
+
43
+ def get_stats(self) -> List[Dict[str, int]]:
44
+ """Get current garbage collection statistics."""
45
+ return gc.get_stats()
46
+
47
+ def get_count(self) -> tuple:
48
+ """Get current garbage collection counts."""
49
+ return gc.get_count()
50
+
51
+ def set_threshold(self, threshold: tuple) -> None:
52
+ """Set garbage collection threshold."""
53
+ gc.set_threshold(*threshold)
54
+
55
+ def get_objects(self) -> List[Any]:
56
+ """Get all objects currently tracked by the garbage collector."""
57
+ return gc.get_objects()
58
+
59
+ def get_referrers(self, obj: Any) -> List[Any]:
60
+ """Get all objects that refer to the given object."""
61
+ return gc.get_referrers(obj)
62
+
63
+ def get_referents(self, obj: Any) -> List[Any]:
64
+ """Get all objects referred to by the given object."""
65
+ return gc.get_referents(obj)
66
+
67
+ def _record_stats(self) -> None:
68
+ """Record current statistics for monitoring."""
69
+ stats = {
70
+ 'timestamp': time.time(),
71
+ 'counts': self.get_count(),
72
+ 'stats': self.get_stats(),
73
+ 'objects_count': len(self.get_objects())
74
+ }
75
+ self.stats_history.append(stats)
76
+
77
+ def get_memory_summary(self) -> Dict[str, Any]:
78
+ """Get a summary of memory usage and garbage collection status."""
79
+ return {
80
+ 'enabled': self.enabled,
81
+ 'counts': self.get_count(),
82
+ 'stats': self.get_stats(),
83
+ 'objects_tracked': len(self.get_objects()),
84
+ 'threshold': gc.get_threshold()
85
+ }
86
+
87
+
88
+ class MemoryProfiler:
89
+ """Memory profiling and monitoring utilities."""
90
+
91
+ def __init__(self):
92
+ self.snapshots = []
93
+ self.weak_refs = {}
94
+
95
+ def take_snapshot(self, label: str = "") -> Dict[str, Any]:
96
+ """
97
+ Take a memory snapshot.
98
+
99
+ Args:
100
+ label: Optional label for the snapshot
101
+
102
+ Returns:
103
+ Dictionary containing snapshot data
104
+ """
105
+ import psutil
106
+ import os
107
+
108
+ process = psutil.Process(os.getpid())
109
+ memory_info = process.memory_info()
110
+
111
+ snapshot = {
112
+ 'label': label,
113
+ 'timestamp': time.time(),
114
+ 'rss': memory_info.rss, # Resident Set Size
115
+ 'vms': memory_info.vms, # Virtual Memory Size
116
+ 'objects_count': len(gc.get_objects()),
117
+ 'gc_counts': gc.get_count()
118
+ }
119
+
120
+ self.snapshots.append(snapshot)
121
+ return snapshot
122
+
123
+ def track_object(self, obj: Any, label: str = "") -> str:
124
+ """
125
+ Track an object using weak reference.
126
+
127
+ Args:
128
+ obj: Object to track
129
+ label: Optional label for the object
130
+
131
+ Returns:
132
+ Tracking ID
133
+ """
134
+ obj_id = str(id(obj))
135
+ try:
136
+ ref = weakref.ref(obj)
137
+ ref_type = 'weak'
138
+ except TypeError:
139
+ ref = obj
140
+ ref_type = 'strong'
141
+
142
+ self.weak_refs[obj_id] = {
143
+ 'ref': ref,
144
+ 'ref_type': ref_type,
145
+ 'label': label,
146
+ 'type': type(obj).__name__,
147
+ 'created': time.time()
148
+ }
149
+ return obj_id
150
+
151
+ def get_tracked_objects(self) -> Dict[str, Any]:
152
+ """Get information about tracked objects."""
153
+ alive = {}
154
+ for obj_id, info in self.weak_refs.items():
155
+ if info.get('ref_type') == 'weak':
156
+ obj = info['ref']()
157
+ else:
158
+ obj = info.get('ref')
159
+ if obj is not None:
160
+ alive[obj_id] = {
161
+ 'label': info['label'],
162
+ 'type': info['type'],
163
+ 'created': info['created'],
164
+ 'alive': True
165
+ }
166
+ else:
167
+ alive[obj_id] = {
168
+ 'label': info['label'],
169
+ 'type': info['type'],
170
+ 'created': info['created'],
171
+ 'alive': False
172
+ }
173
+ return alive
174
+
175
+ def compare_snapshots(self, index1: int, index2: int) -> Dict[str, Any]:
176
+ """
177
+ Compare two memory snapshots.
178
+
179
+ Args:
180
+ index1: Index of first snapshot
181
+ index2: Index of second snapshot
182
+
183
+ Returns:
184
+ Comparison data
185
+ """
186
+ if index1 >= len(self.snapshots) or index2 >= len(self.snapshots):
187
+ raise IndexError("Snapshot index out of range")
188
+
189
+ snap1 = self.snapshots[index1]
190
+ snap2 = self.snapshots[index2]
191
+
192
+ return {
193
+ 'time_diff': snap2['timestamp'] - snap1['timestamp'],
194
+ 'rss_diff': snap2['rss'] - snap1['rss'],
195
+ 'vms_diff': snap2['vms'] - snap1['vms'],
196
+ 'objects_diff': snap2['objects_count'] - snap1['objects_count'],
197
+ 'label1': snap1.get('label', f'Snapshot {index1}'),
198
+ 'label2': snap2.get('label', f'Snapshot {index2}')
199
+ }
200
+
201
+ def clear_snapshots(self) -> None:
202
+ """Clear all stored snapshots."""
203
+ self.snapshots.clear()
204
+
205
+ def clear_tracking(self) -> None:
206
+ """Clear all tracked objects."""
207
+ self.weak_refs.clear()
klo/utils.py ADDED
@@ -0,0 +1,262 @@
1
+ """
2
+ Utility functions for garbage collection and memory management.
3
+ """
4
+
5
+ import gc
6
+ import os
7
+ import tempfile
8
+ import shutil
9
+ import time
10
+ import sys
11
+ from typing import List, Dict, Any, Optional, Callable
12
+ import logging
13
+
14
+ try:
15
+ import psutil
16
+ except ImportError: # pragma: no cover
17
+ psutil = None
18
+
19
+
20
+ def cleanup_temp_files(pattern: str = "*") -> int:
21
+ """
22
+ Clean up temporary files matching a pattern.
23
+
24
+ Args:
25
+ pattern: File pattern to match (default: "*")
26
+
27
+ Returns:
28
+ Number of files cleaned up
29
+ """
30
+ temp_dir = tempfile.gettempdir()
31
+ cleaned_count = 0
32
+
33
+ try:
34
+ for filename in os.listdir(temp_dir):
35
+ if pattern == "*" or pattern in filename:
36
+ file_path = os.path.join(temp_dir, filename)
37
+ try:
38
+ if os.path.isfile(file_path):
39
+ os.remove(file_path)
40
+ cleaned_count += 1
41
+ except (PermissionError, OSError):
42
+ # Skip files we can't remove
43
+ continue
44
+ except (PermissionError, OSError):
45
+ pass
46
+
47
+ return cleaned_count
48
+
49
+
50
+ def monitor_memory_usage(duration: int = 60, interval: float = 1.0) -> List[Dict[str, Any]]:
51
+ """
52
+ Monitor memory usage over time.
53
+
54
+ Args:
55
+ duration: Monitoring duration in seconds
56
+ interval: Sampling interval in seconds
57
+
58
+ Returns:
59
+ List of memory usage samples
60
+ """
61
+ if psutil is None or sys.modules.get('psutil') is None:
62
+ raise ImportError("psutil is required for memory monitoring. Install with: pip install psutil")
63
+
64
+ process = psutil.Process(psutil.os.getpid())
65
+ samples = []
66
+ start_time = time.time()
67
+
68
+ while time.time() - start_time < duration:
69
+ memory_info = process.memory_info()
70
+ sample = {
71
+ 'timestamp': time.time(),
72
+ 'rss': memory_info.rss,
73
+ 'vms': memory_info.vms,
74
+ 'percent': process.memory_percent(),
75
+ 'objects_count': len(gc.get_objects()),
76
+ 'gc_counts': gc.get_count()
77
+ }
78
+ samples.append(sample)
79
+ time.sleep(interval)
80
+
81
+ return samples
82
+
83
+
84
+ def force_garbage_collection(verbose: bool = False) -> Dict[str, int]:
85
+ """
86
+ Force garbage collection on all generations.
87
+
88
+ Args:
89
+ verbose: If True, print detailed information
90
+
91
+ Returns:
92
+ Dictionary with collection results per generation
93
+ """
94
+ results = {}
95
+
96
+ for generation in range(3):
97
+ before_count = len(gc.get_objects())
98
+ collected = gc.collect(generation)
99
+ after_count = len(gc.get_objects())
100
+
101
+ results[f'gen_{generation}'] = {
102
+ 'collected': collected,
103
+ 'before_count': before_count,
104
+ 'after_count': after_count,
105
+ 'net_change': after_count - before_count
106
+ }
107
+
108
+ if verbose:
109
+ print(f"Generation {generation}: Collected {collected} objects, "
110
+ f"Net change: {after_count - before_count}")
111
+
112
+ return results
113
+
114
+
115
+ def find_object_cycles(obj: Any, max_depth: int = 10) -> List[List[Any]]:
116
+ """
117
+ Find reference cycles involving the given object.
118
+
119
+ Args:
120
+ obj: Object to analyze
121
+ max_depth: Maximum search depth
122
+
123
+ Returns:
124
+ List of reference cycles found
125
+ """
126
+ cycles = []
127
+ visited = set()
128
+ path = []
129
+
130
+ def _find_cycles(current_obj, depth):
131
+ if depth > max_depth:
132
+ return
133
+
134
+ obj_id = id(current_obj)
135
+ if obj_id in visited:
136
+ if current_obj in path:
137
+ # Found a cycle
138
+ cycle_start = path.index(current_obj)
139
+ cycles.append(path[cycle_start:] + [current_obj])
140
+ return
141
+
142
+ visited.add(obj_id)
143
+ path.append(current_obj)
144
+
145
+ try:
146
+ referents = gc.get_referents(current_obj)
147
+ for ref in referents:
148
+ _find_cycles(ref, depth + 1)
149
+ except:
150
+ # Skip objects that can't be analyzed
151
+ pass
152
+
153
+ path.pop()
154
+ visited.remove(obj_id)
155
+
156
+ _find_cycles(obj, 0)
157
+ return cycles
158
+
159
+
160
+ def get_object_size(obj: Any) -> int:
161
+ """
162
+ Get approximate size of an object in bytes.
163
+
164
+ Args:
165
+ obj: Object to measure
166
+
167
+ Returns:
168
+ Approximate size in bytes
169
+ """
170
+ try:
171
+ import sys
172
+ return sys.getsizeof(obj)
173
+ except:
174
+ return 0
175
+
176
+
177
+ def analyze_memory_usage() -> Dict[str, Any]:
178
+ """
179
+ Analyze current memory usage and provide statistics.
180
+
181
+ Returns:
182
+ Dictionary with memory analysis
183
+ """
184
+ if psutil is None or sys.modules.get('psutil') is None:
185
+ raise ImportError("psutil is required for memory analysis. Install with: pip install psutil")
186
+
187
+ process = psutil.Process(psutil.os.getpid())
188
+ memory_info = process.memory_info()
189
+
190
+ # Analyze object types
191
+ all_objects = gc.get_objects()
192
+ type_counts = {}
193
+ for obj in all_objects:
194
+ obj_type = type(obj).__name__
195
+ type_counts[obj_type] = type_counts.get(obj_type, 0) + 1
196
+
197
+ # Get top 10 most common types
198
+ sorted_types = sorted(type_counts.items(), key=lambda x: x[1], reverse=True)[:10]
199
+
200
+ return {
201
+ 'timestamp': time.time(),
202
+ 'memory': {
203
+ 'rss': memory_info.rss,
204
+ 'vms': memory_info.vms,
205
+ 'percent': process.memory_percent()
206
+ },
207
+ 'gc': {
208
+ 'enabled': gc.isenabled(),
209
+ 'counts': gc.get_count(),
210
+ 'threshold': gc.get_threshold(),
211
+ 'stats': gc.get_stats()
212
+ },
213
+ 'objects': {
214
+ 'total_count': len(all_objects),
215
+ 'top_types': sorted_types
216
+ }
217
+ }
218
+
219
+
220
+ def set_debug_gc(flags: int = gc.DEBUG_STATS) -> None:
221
+ """
222
+ Set garbage collection debug flags.
223
+
224
+ Args:
225
+ flags: Debug flags (gc.DEBUG_STATS, gc.DEBUG_LEAK, etc.)
226
+ """
227
+ gc.set_debug(flags)
228
+
229
+
230
+ def clear_gc_debug() -> None:
231
+ """Clear garbage collection debug flags."""
232
+ gc.set_debug(0)
233
+
234
+
235
+ def create_memory_logger(log_file: str = "gc_memory.log") -> logging.Logger:
236
+ """
237
+ Create a logger for memory-related events.
238
+
239
+ Args:
240
+ log_file: Log file path
241
+
242
+ Returns:
243
+ Configured logger instance
244
+ """
245
+ logger = logging.getLogger("gc_memory")
246
+ logger.setLevel(logging.INFO)
247
+
248
+ # Create file handler
249
+ handler = logging.FileHandler(log_file)
250
+ handler.setLevel(logging.INFO)
251
+
252
+ # Create formatter
253
+ formatter = logging.Formatter(
254
+ '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
255
+ )
256
+ handler.setFormatter(formatter)
257
+
258
+ # Add handler to logger
259
+ if not logger.handlers:
260
+ logger.addHandler(handler)
261
+
262
+ return logger
@@ -0,0 +1,206 @@
1
+ Metadata-Version: 2.4
2
+ Name: klo-git
3
+ Version: 0.1.8
4
+ Summary: Python package for garbage collection utilities and memory management
5
+ Author-email: Tom Sapletta <tom@example.com>, Tom Sapletta <tom@sapletta.com>
6
+ Maintainer-email: Tom Sapletta <tom@example.com>
7
+ License-Expression: Apache-2.0
8
+ Project-URL: Homepage, https://github.com/tom-sapletta/gc
9
+ Project-URL: Repository, https://github.com/tom-sapletta/gc.git
10
+ Project-URL: Issues, https://github.com/tom-sapletta/gc/issues
11
+ Keywords: garbage-collection,memory,profiling,utilities
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.8
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
22
+ Classifier: Topic :: System :: Monitoring
23
+ Classifier: Topic :: Software Development :: Testing
24
+ Requires-Python: >=3.8
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Requires-Dist: psutil>=5.8.0
28
+ Provides-Extra: dev
29
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
30
+ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
31
+ Requires-Dist: twine>=4.0.0; extra == "dev"
32
+ Requires-Dist: build>=1.0.0; extra == "dev"
33
+ Requires-Dist: black>=22.0.0; extra == "dev"
34
+ Requires-Dist: flake8>=5.0.0; extra == "dev"
35
+ Requires-Dist: mypy>=1.0.0; extra == "dev"
36
+ Provides-Extra: test
37
+ Requires-Dist: pytest>=7.0.0; extra == "test"
38
+ Requires-Dist: pytest-cov>=4.0.0; extra == "test"
39
+ Dynamic: license-file
40
+
41
+ # gc
42
+
43
+ Python package for garbage collection utilities and memory management.
44
+
45
+ ## Overview
46
+
47
+ The `gc` package provides comprehensive tools and utilities for working with Python's garbage collector, memory profiling, and cleanup operations. It offers enhanced garbage collection control, memory monitoring, and debugging capabilities.
48
+
49
+ ## Features
50
+
51
+ - **Enhanced Garbage Collection**: Control and monitor Python's garbage collector with detailed statistics
52
+ - **Memory Profiling**: Track memory usage over time and analyze memory patterns
53
+ - **Object Tracking**: Monitor specific objects using weak references
54
+ - **Reference Cycle Detection**: Find and analyze reference cycles in your code
55
+ - **Memory Analysis**: Comprehensive memory usage analysis and reporting
56
+ - **Utility Functions**: Common garbage collection and memory management tasks
57
+
58
+ ## Installation
59
+
60
+ ```bash
61
+ pip install gc
62
+ ```
63
+
64
+ ### Development Installation
65
+
66
+ ```bash
67
+ git clone https://github.com/tom-sapletta/gc.git
68
+ cd gc
69
+ pip install -e ".[dev]"
70
+ ```
71
+
72
+ ## Quick Start
73
+
74
+ ### Basic Garbage Collection Control
75
+
76
+ ```python
77
+ from gc import GarbageCollector
78
+
79
+ # Create a garbage collector instance
80
+ gc_manager = GarbageCollector()
81
+
82
+ # Force garbage collection
83
+ collected = gc_manager.collect()
84
+ print(f"Collected {collected} objects")
85
+
86
+ # Get memory summary
87
+ summary = gc_manager.get_memory_summary()
88
+ print(summary)
89
+ ```
90
+
91
+ ### Memory Profiling
92
+
93
+ ```python
94
+ from gc import MemoryProfiler
95
+
96
+ # Create a profiler instance
97
+ profiler = MemoryProfiler()
98
+
99
+ # Take a memory snapshot
100
+ profiler.take_snapshot("before_operation")
101
+
102
+ # Your code here...
103
+ data = [list(range(1000)) for _ in range(100)]
104
+
105
+ # Take another snapshot
106
+ profiler.take_snapshot("after_operation")
107
+
108
+ # Compare snapshots
109
+ comparison = profiler.compare_snapshots(0, 1)
110
+ print(f"Memory change: {comparison['rss_diff']} bytes")
111
+ ```
112
+
113
+ ### Memory Monitoring
114
+
115
+ ```python
116
+ from gc.utils import monitor_memory_usage
117
+
118
+ # Monitor memory for 60 seconds
119
+ samples = monitor_memory_usage(duration=60, interval=1.0)
120
+
121
+ for sample in samples:
122
+ print(f"Memory: {sample['rss']} bytes, Objects: {sample['objects_count']}")
123
+ ```
124
+
125
+ ## API Reference
126
+
127
+ ### GarbageCollector
128
+
129
+ Main class for garbage collection control and monitoring.
130
+
131
+ #### Methods
132
+
133
+ - `enable()` - Enable garbage collection
134
+ - `disable()` - Disable garbage collection
135
+ - `collect(generation=2)` - Force garbage collection
136
+ - `get_stats()` - Get garbage collection statistics
137
+ - `get_memory_summary()` - Get comprehensive memory summary
138
+
139
+ ### MemoryProfiler
140
+
141
+ Class for memory profiling and object tracking.
142
+
143
+ #### Methods
144
+
145
+ - `take_snapshot(label="")` - Take a memory snapshot
146
+ - `track_object(obj, label="")` - Track an object with weak reference
147
+ - `compare_snapshots(index1, index2)` - Compare two memory snapshots
148
+ - `get_tracked_objects()` - Get information about tracked objects
149
+
150
+ ### Utility Functions
151
+
152
+ - `cleanup_temp_files(pattern="*")` - Clean up temporary files
153
+ - `monitor_memory_usage(duration=60, interval=1.0)` - Monitor memory usage
154
+ - `force_garbage_collection(verbose=False)` - Force garbage collection on all generations
155
+ - `find_object_cycles(obj, max_depth=10)` - Find reference cycles
156
+ - `analyze_memory_usage()` - Comprehensive memory analysis
157
+
158
+ ## Requirements
159
+
160
+ - Python 3.8+
161
+ - psutil>=5.8.0
162
+
163
+ ## Development
164
+
165
+ ### Running Tests
166
+
167
+ ```bash
168
+ pytest
169
+ ```
170
+
171
+ ### Code Formatting
172
+
173
+ ```bash
174
+ black gc/
175
+ ```
176
+
177
+ ### Type Checking
178
+
179
+ ```bash
180
+ mypy gc/
181
+ ```
182
+
183
+ ## License
184
+
185
+ Apache License 2.0 - see [LICENSE](LICENSE) for details.
186
+
187
+ ## Contributing
188
+
189
+ Contributions are welcome! Please read the CONTRIBUTING.md file for details on our code of conduct and the process for submitting pull requests.
190
+
191
+ ## Changelog
192
+
193
+ ### 0.1.0
194
+
195
+ - Initial release
196
+ - Basic garbage collection control
197
+ - Memory profiling capabilities
198
+ - Utility functions for memory management
199
+
200
+ ## License
201
+
202
+ Apache License 2.0 - see [LICENSE](LICENSE) for details.
203
+
204
+ ## Author
205
+
206
+ Created by **Tom Sapletta** - [tom@sapletta.com](mailto:tom@sapletta.com)
@@ -0,0 +1,10 @@
1
+ klo/__init__.py,sha256=oqB9G2rzLJvc4w408bfwQ0sx5anfAbfp01lb2CNtBy8,524
2
+ klo/cli.py,sha256=U4hBFsDM8QhHrm5eKOXDK1skg5Fv8gDT_9fB5bd56qM,4521
3
+ klo/core.py,sha256=JJHWESvdycpeLSKo1XYwwPiyjVQx08GN2IkajB5623k,6265
4
+ klo/utils.py,sha256=GFJCVdyoq1zV-NfMUM6P9Si9vrhSmIZAmcXtbUyAREk,6840
5
+ klo_git-0.1.8.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
6
+ klo_git-0.1.8.dist-info/METADATA,sha256=RGzzjjL7z4xLLo-j0bMsMmqB5qipsf0xwJqbu5i7zOs,5616
7
+ klo_git-0.1.8.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
8
+ klo_git-0.1.8.dist-info/entry_points.txt,sha256=aOGJ6QA70CNQ7AzI8xRKTaHstvrWUOLsugOIIKxQkk0,36
9
+ klo_git-0.1.8.dist-info/top_level.txt,sha256=5H04TdQNrEqXthNn868GbMryKuFSFtwqFO53KaR3We0,4
10
+ klo_git-0.1.8.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ gc = klo.cli:main
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
@@ -0,0 +1 @@
1
+ klo