0
# Core Functions
1

2
Primary API functions for version discovery and update checking across multiple hosting platforms. These functions provide the main programmatic interface for determining latest versions and checking for available updates.
3

4
## Capabilities
5

6
### Latest Version Discovery
7

8
Discovers the latest stable version of a software project from various hosting platforms including GitHub, GitLab, PyPI, BitBucket, and others. Supports extensive filtering and output formatting options.
9

10
```python { .api }
11
def latest(
12
    repo: str,
13
    output_format: str = "version",
14
    pre_ok: bool = False,
15
    assets_filter: Union[str, Pattern] = None,
16
    short_urls: bool = False,
17
    major: str = None,
18
    only: str = None,
19
    at: str = None,
20
    having_asset: str = None,
21
    exclude: str = None,
22
    even: bool = False,
23
    formal: bool = False
24
) -> Union[Version, dict, str, None]:
25
    """
26
    Find the latest release version for a project.
27

28
    Parameters:
29
    - repo: Repository specifier (URL, owner/name, or package name)
30
    - output_format: Return format - "version" (default), "json", "dict", "assets", "source", "tag"
31
    - pre_ok: Whether to accept pre-release versions as latest
32
    - assets_filter: Regex pattern for filtering release assets
33
    - short_urls: Return shorter URLs when possible
34
    - major: Only consider versions descended from this major version
35
    - only: Only consider tags containing this text (supports regex with ~ prefix, negation with !)
36
    - at: Platform hint ("github", "gitlab", "pip", etc.) for disambiguation
37
    - having_asset: Only consider releases that have assets matching this pattern
38
    - exclude: Exclude versions matching this pattern
39
    - even: Only consider even version numbers
40
    - formal: Only consider formal releases (no pre-release indicators)
41

42
    Returns:
43
    - With output_format="version": Version object or None
44
    - With output_format="dict": Dictionary with version info or False
45
    - With output_format="json": JSON string representation
46
    - With output_format="assets": List of asset URLs
47
    - With output_format="source": Source download URL
48
    - With output_format="tag": Tag name string
49
    """
50
```
51

52
### Update Availability Check
53

54
Checks whether a newer version is available for a given current version of a software project.
55

56
```python { .api }
57
def has_update(
58
    repo: str,
59
    current_version: str,
60
    pre_ok: bool = False,
61
    at: str = None
62
) -> Union[Version, bool]:
63
    """
64
    Check if there is an update available for the current version.
65

66
    Parameters:
67
    - repo: Repository specifier in any supported format
68
    - current_version: Current version string to check against
69
    - pre_ok: Whether pre-releases can be accepted as newer versions
70
    - at: Platform hint for disambiguation when repo is ambiguous
71

72
    Returns:
73
    - Version object if newer version found
74
    - False if no update available or current version is latest
75
    """
76
```
77

78
### Version Validation
79

80
Validates and normalizes version strings according to packaging standards with lastversion-specific enhancements.
81

82
```python { .api }
83
def check_version(value: str) -> Version:
84
    """
85
    Validate and parse a version string.
86

87
    Parameters:
88
    - value: Version string to validate and parse
89

90
    Returns:
91
    - Version object with normalized version
92
    
93
    Raises:
94
    - InvalidVersion: If version string cannot be parsed
95
    """
96
```
97

98
### Command Line Interface
99

100
Main entry point for command-line usage providing access to all functionality through CLI arguments.
101

102
```python { .api }
103
def main(argv: List[str] = None) -> None:
104
    """
105
    Main entry point for CLI usage.
106

107
    Parameters:
108
    - argv: Command line arguments (uses sys.argv if None)
109
    
110
    Provides CLI access to:
111
    - Version discovery with various output formats
112
    - Asset downloading and extraction
113
    - Update checking
114
    - Installation of discovered releases
115
    - RPM spec file integration
116
    """
117
```
118

119
## Usage Examples
120

121
### Basic Version Discovery
122

123
```python
124
from lastversion import latest
125

126
# Get latest version of a GitHub project
127
version = latest("mautic/mautic")
128
print(f"Latest version: {version}")  # e.g., "4.4.5"
129

130
# Get detailed release information
131
release_info = latest("mautic/mautic", output_format="dict")
132
print(f"Release date: {release_info.get('date')}")
133
print(f"Download URL: {release_info.get('download_url')}")
134
```
135

136
### Platform-Specific Queries
137

138
```python
139
from lastversion import latest
140

141
# Check PyPI package version
142
requests_version = latest("requests", at="pip")
143
print(f"Latest requests: {requests_version}")
144

145
# Check GitLab project
146
gitlab_version = latest("gitlab-org/gitlab", at="gitlab")
147
print(f"Latest GitLab: {gitlab_version}")
148
```
149

150
### Update Checking
151

152
```python
153
from lastversion import has_update
154

155
# Check for updates
156
current = "1.2.3"
157
update = has_update("owner/project", current)
158

159
if update:
160
    print(f"Update available: {current} → {update}")
161
else:
162
    print("Already at latest version")
163
```
164

165
### Advanced Filtering
166

167
```python
168
from lastversion import latest
169

170
# Only stable releases from a major version
171
version = latest("kubernetes/kubernetes", major="1.28", pre_ok=False)
172

173
# Filter by asset availability
174
version = latest("project/name", having_asset=r".*\.dmg$")
175

176
# Only even version numbers
177
version = latest("project/name", even=True)
178

179
# Exclude specific patterns
180
version = latest("project/name", exclude=r".*beta.*")
181
```
182

183
### Output Format Options
184

185
```python
186
from lastversion import latest
187

188
repo = "apache/httpd"
189

190
# Get Version object (default)
191
version_obj = latest(repo)
192

193
# Get as dictionary
194
version_dict = latest(repo, output_format="dict")
195

196
# Get as JSON string
197
version_json = latest(repo, output_format="json")
198

199
# Get source download URL
200
source_url = latest(repo, output_format="source")
201

202
# Get release assets
203
assets = latest(repo, output_format="assets")
204

205
# Get git tag name
206
tag = latest(repo, output_format="tag")
207
```