0
# lastversion
1

2
A comprehensive Python CLI tool and library that helps developers and system administrators determine the latest stable version of software projects across multiple platforms and repositories. It intelligently handles inconsistent version formatting, filters out pre-releases, and provides programmatic access to version information from GitHub, GitLab, BitBucket, PyPI, Mercurial, SourceForge, Wikipedia, WordPress plugin directory, and RSS/ATOM feeds.
3

4
## Package Information
5

6
- **Package Name**: lastversion
7
- **Language**: Python
8
- **Installation**: `pip install lastversion`
9
- **Python Requirements**: Python ≥3.6
10

11
## Core Imports
12

13
```python
14
import lastversion
15
```
16

17
Most common imports for library usage:
18

19
```python
20
from lastversion import latest, has_update
21
```
22

23
For version handling:
24

25
```python
26
from lastversion.version import Version
27
```
28

29
For utilities:
30

31
```python
32
from lastversion.utils import download_file, extract_file
33
```
34

35
## Basic Usage
36

37
```python
38
from lastversion import latest, has_update
39

40
# Get the latest version of a project
41
latest_version = latest("mautic/mautic")
42
print(f"Latest Mautic version: {latest_version}")
43

44
# Check if an update is available
45
current_version = "1.2.3"
46
update_available = has_update("mautic/mautic", current_version)
47
if update_available:
48
    print(f"Update available: {update_available}")
49
else:
50
    print("No update available")
51

52
# Get version information as dictionary
53
version_info = latest("mautic/mautic", output_format="dict")
54
print(f"Release info: {version_info}")
55

56
# Check PyPI packages specifically
57
latest_requests = latest("requests", at="pip")
58
print(f"Latest requests version: {latest_requests}")
59

60
# Download the latest release
61
latest("apache/incubator-pagespeed-ngx", output_format="source")
62
```
63

64
## Architecture
65

66
lastversion employs a flexible repository holder architecture that enables extensible support for multiple hosting platforms:
67

68
- **Core Functions**: High-level API functions (`latest()`, `has_update()`) that orchestrate version discovery
69
- **Repository Holders**: Platform-specific adapters for GitHub, GitLab, PyPI, etc., each implementing the BaseProjectHolder interface
70
- **Version Handling**: Enhanced Version class extending PEP 440 with intelligent normalization for real-world version inconsistencies
71
- **Holder Factory**: Dynamic holder selection based on repository URL patterns and explicit platform hints
72
- **Utility Layer**: File operations, platform compatibility checks, and installation helpers
73

74
This design allows lastversion to handle diverse version formats and repository structures while maintaining a consistent API for consumers.
75

76
## Capabilities
77

78
### Core Functions
79

80
Primary API functions for version discovery and update checking. These functions provide the main interface for determining latest versions across multiple platforms and checking for available updates.
81

82
```python { .api }
83
def latest(repo, output_format="version", pre_ok=False, assets_filter=None, short_urls=False, major=None, only=None, at=None, having_asset=None, exclude=None, even=False, formal=False): ...
84
def has_update(repo, current_version, pre_ok=False, at=None): ...
85
def check_version(value): ...
86
```
87

88
[Core Functions](./core-functions.md)
89

90
### Version Handling
91

92
Enhanced version class and utilities for parsing, normalizing, and comparing software versions. Extends PEP 440 with intelligent handling of real-world version inconsistencies.
93

94
```python { .api }
95
class Version(PackagingVersion):
96
    def __init__(self, version: str): ...
97
    @staticmethod
98
    def special_cases_transformation(version: str) -> str: ...
99
```
100

101
[Version Handling](./version-handling.md)
102

103
### Utility Functions
104

105
File operations, platform compatibility checks, and system integration utilities. Includes download, extraction, and installation helpers for retrieved software releases.
106

107
```python { .api }
108
def download_file(url: str, local_filename: str = None) -> str: ...
109
def extract_file(url: str, to_dir: str = ".") -> Any: ...
110
def rpm_installed_version(name: str) -> str: ...
111
```
112

113
[Utility Functions](./utilities.md)
114

115
### Repository Holders
116

117
Platform-specific adapters for different hosting services and package repositories. Each holder implements specialized logic for parsing version information from its respective platform.
118

119
```python { .api }
120
class HolderFactory:
121
    HOLDERS: dict
122
    DEFAULT_HOLDER: str
123
    @staticmethod
124
    def get_instance_for_repo(repo: str, at: str = None): ...
125
```
126

127
[Repository Holders](./repository-holders.md)
128

129
### Exception Handling
130

131
Custom exception classes for specific error conditions encountered during version discovery and file operations.
132

133
```python { .api }
134
class ApiCredentialsError(Exception): ...
135
class BadProjectError(Exception): ...
136
class TarPathTraversalException(Exception): ...
137
```
138

139
[Exception Handling](./exceptions.md)
140

141
## Types
142

143
```python { .api }
144
# Version type that extends packaging.version.Version with additional normalization
145
class Version(PackagingVersion):
146
    def __init__(self, version: str): ...
147
    def __str__(self) -> str: ...
148
    def __eq__(self, other) -> bool: ...
149
    def __lt__(self, other) -> bool: ...
150
    def __le__(self, other) -> bool: ...
151
    def __gt__(self, other) -> bool: ...
152
    def __ge__(self, other) -> bool: ...
153

154
# Base repository holder interface
155
class BaseProjectHolder:
156
    CACHE_DISABLED: bool
157
    
158
# Holder factory for creating platform-specific handlers
159
class HolderFactory:
160
    HOLDERS: dict[str, type]
161
    DEFAULT_HOLDER: str
162
```