0
# Message Access and Selection
1

2
Methods for accessing individual messages, iterating through files, and selecting messages based on criteria. Supports flexible filtering with scalars, sequences, and functions.
3

4
## Capabilities
5

6
### Direct Message Access
7

8
Access specific messages by position or through indexing.
9

10
```python { .api }
11
class open:
12
    def message(self, N: int):
13
        """
14
        Get specific message by number (1-based).
15
        Positions iterator at this message.
16
        
17
        Parameters:
18
        - N: int, message number (1-based indexing)
19
        
20
        Returns:
21
        gribmessage object
22
        """
23
        
24
    def __getitem__(self, key):
25
        """
26
        Index-based message access.
27
        Does not change iterator position.
28
        
29
        Parameters:
30
        - key: int or slice, message index (0-based) or slice object
31
        
32
        Returns:
33
        gribmessage object or list of gribmessage objects
34
        """
35
```
36

37
Usage example:
38
```python
39
grbs = pygrib.open('weather.grb')
40

41
# Get 3rd message (1-based) - moves iterator
42
grb = grbs.message(3)
43

44
# Get 2nd message (0-based) - preserves iterator position  
45
grb = grbs[1]
46

47
# Get multiple messages via slicing
48
first_five = grbs[0:5]
49
every_other = grbs[::2]
50
last_three = grbs[-3:]
51
```
52

53
### Message Selection and Filtering
54

55
Select messages based on GRIB key criteria with support for scalars, sequences, and functions.
56

57
```python { .api }
58
class open:
59
    def select(self, **kwargs):
60
        """
61
        Select messages matching specified key/value criteria.
62
        
63
        Parameters:
64
        - **kwargs: GRIB key/value pairs for filtering
65
          Values can be:
66
          - Scalar: exact match
67
          - Sequence: match any value in sequence  
68
          - Callable: function that returns True for matches
69
        
70
        Returns:
71
        List of gribmessage objects matching criteria
72
        """
73
        
74
    def __call__(self, **kwargs):
75
        """Alias for select() method"""
76
```
77

78
Usage example:
79
```python
80
grbs = pygrib.open('weather.grb')
81

82
# Select by single criteria
83
temp_500 = grbs.select(shortName='t', level=500)
84

85
# Select by multiple values
86
temp_levels = grbs.select(shortName='t', level=(850, 700, 500))
87

88
# Select using function criteria  
89
low_levels = grbs.select(shortName='t', level=lambda l: l > 850)
90

91
# Select by date/time
92
from datetime import datetime
93
today_data = grbs.select(validDate=datetime(2023, 12, 1, 0))
94

95
# Using __call__ method (equivalent to select)
96
wind_data = grbs(shortName=['u', 'v'], level=250)
97
```
98

99
### Creating Messages from Strings
100

101
Create GRIB message objects from binary GRIB data.
102

103
```python { .api }
104
def fromstring(gribstring: bytes):
105
    """
106
    Create gribmessage object from binary GRIB string.
107
    
108
    Parameters:
109
    - gribstring: bytes, binary GRIB message data
110
    
111
    Returns:
112
    gribmessage object
113
    """
114
```
115

116
Usage example:
117
```python
118
# Get binary representation of a message
119
grbs = pygrib.open('weather.grb')
120
grb = grbs.readline()
121
binary_data = grb.tostring()
122

123
# Recreate message from binary data
124
new_grb = pygrib.fromstring(binary_data)
125
print(new_grb)  # Same as original message
126
```
127

128
### Message Reloading
129

130
Reload message data from the source file to refresh any cached information.
131

132
```python { .api }
133
def reload(grb):
134
    """
135
    Reload gribmessage from file to refresh data.
136
    
137
    Parameters:
138
    - grb: gribmessage, message to reload
139
    
140
    Returns:
141
    New gribmessage object with refreshed data
142
    """
143
```
144

145
Usage example:
146
```python
147
grbs = pygrib.open('weather.grb')
148
grb = grbs.readline()
149

150
# Modify message (example)
151
grb['forecastTime'] = 120
152

153
# Reload original data from file
154
original_grb = pygrib.reload(grb)
155
print(f"Modified: {grb['forecastTime']}")
156
print(f"Original: {original_grb['forecastTime']}")
157
```
158

159
### Advanced Selection Examples
160

161
Complex filtering scenarios using multiple criteria types.
162

163
```python
164
grbs = pygrib.open('weather.grb')
165

166
# Temperature at specific levels  
167
temps = grbs.select(
168
    shortName='t',
169
    level=(1000, 850, 700, 500, 250),
170
    typeOfLevel='isobaricInhPa'
171
)
172

173
# Surface variables
174
surface_vars = grbs.select(
175
    shortName=['sp', 'msl', '2t', '10u', '10v'],
176
    typeOfLevel='surface'
177
)
178

179
# Forecast data for specific time range
180
from datetime import datetime
181
forecast_range = grbs.select(
182
    validDate=lambda d: datetime(2023, 12, 1) <= d <= datetime(2023, 12, 2),
183
    level=lambda l: l <= 100  # Upper atmosphere
184
)
185

186
# Select by parameter ID
187
geopotential = grbs.select(paramId=129)
188

189
# Multi-criteria complex selection
190
upper_air_winds = grbs.select(
191
    shortName=['u', 'v'],
192
    level=lambda l: 100 <= l <= 1000,
193
    typeOfLevel='isobaricInhPa', 
194
    step=lambda s: s % 6 == 0  # Every 6 hours
195
)
196
```
197

198
## Selection Performance Notes
199

200
- Use `select()` for flexible criteria matching with moderate performance
201
- For large files with frequent searches, consider using `index` class for better performance
202
- Function-based criteria (lambdas) are evaluated for each message and may be slower
203
- Sequence matching is efficient for small-to-medium lists of values
204
- Multi-field messages require special handling - see documentation warnings