0
# Character and Company Operations
1

2
Character and company search and retrieval functionality for accessing information about fictional characters and production companies in the IMDb database.
3

4
## Character Operations
5

6
### Character Search
7

8
Search for fictional characters by name with configurable result limits.
9

10
```python { .api }
11
def search_character(name, results=None):
12
    """
13
    Search for characters by name.
14
    
15
    Parameters:
16
    - name: str - Character name to search for
17
    - results: int, optional - Maximum number of results (default: instance default)
18
    
19
    Returns:
20
    list: List of Character objects with basic information
21
    """
22
```
23

24
**Usage Example:**
25

26
```python
27
from imdb import IMDb
28

29
ia = IMDb()
30

31
# Basic character search
32
characters = ia.search_character('James Bond')
33
print(f"Found {len(characters)} characters")
34
for character in characters[:3]:
35
    print(f"- {character['name']} (ID: {character.characterID})")
36

37
# Search for specific character
38
characters = ia.search_character('Sherlock Holmes')
39
```
40

41
### Character Retrieval
42

43
Retrieve detailed character information by IMDb ID with configurable information sets.
44

45
```python { .api }
46
def get_character(characterID, info=('main', 'filmography', 'biography'), modFunct=None):
47
    """
48
    Get character by ID with specified information sets.
49
    
50
    Parameters:
51
    - characterID: str - Character ID (internal or IMDb format)
52
    - info: tuple/list - Information sets to retrieve ('main', 'filmography', 'biography')
53
    - modFunct: function, optional - String modification function
54
    
55
    Returns:
56
    Character: Character object with requested information
57
    """
58
```
59

60
**Available Information Sets:**
61
- `'main'` - Basic character information (name, description, etc.)
62
- `'filmography'` - Movies/shows the character appears in
63
- `'biography'` - Character background and description
64

65
**Usage Example:**
66

67
```python
68
from imdb import IMDb
69

70
ia = IMDb()
71

72
# Get character with basic info
73
character = ia.get_character('0000196')  # James Bond
74
print(f"Character: {character['name']}")
75

76
# Get character with filmography
77
character = ia.get_character('0000196', info=['main', 'filmography'])
78

79
# Access character appearances
80
if 'filmography' in character:
81
    appearances = character['filmography']
82
    print(f"Appears in {len(appearances)} productions")
83
    for movie in appearances[:5]:
84
        print(f"  - {movie['title']} ({movie.get('year', 'N/A')})")
85
```
86

87
### Character Information Sets
88

89
Get available information sets for character objects.
90

91
```python { .api }
92
def get_character_infoset():
93
    """
94
    Get list of available information sets for characters.
95
    
96
    Returns:
97
    list: Available information set names
98
    """
99
```
100

101
### Character Object Creation
102

103
Create new Character objects with specified parameters.
104

105
```python { .api }
106
def new_character(*arguments, **keywords):
107
    """
108
    Create a new Character object.
109
    
110
    Parameters:
111
    - *arguments: Variable arguments for Character constructor
112
    - **keywords: Keyword arguments for Character constructor
113
    
114
    Returns:
115
    Character: New Character object instance
116
    """
117
```
118

119
## Company Operations
120

121
### Company Search
122

123
Search for production companies by name with configurable result limits.
124

125
```python { .api }
126
def search_company(name, results=None):
127
    """
128
    Search for companies by name.
129
    
130
    Parameters:
131
    - name: str - Company name to search for
132
    - results: int, optional - Maximum number of results (default: instance default)
133
    
134
    Returns:
135
    list: List of Company objects with basic information
136
    """
137
```
138

139
**Usage Example:**
140

141
```python
142
from imdb import IMDb
143

144
ia = IMDb()
145

146
# Basic company search
147
companies = ia.search_company('Warner Bros')
148
print(f"Found {len(companies)} companies")
149
for company in companies[:3]:
150
    print(f"- {company['name']} (ID: {company.companyID})")
151

152
# Search for specific company
153
companies = ia.search_company('Pixar')
154
```
155

156
### Company Retrieval
157

158
Retrieve detailed company information by IMDb ID with configurable information sets.
159

160
```python { .api }
161
def get_company(companyID, info=('main',), modFunct=None):
162
    """
163
    Get company by ID with specified information sets.
164
    
165
    Parameters:
166
    - companyID: str - Company ID (internal or IMDb format)
167
    - info: tuple/list - Information sets to retrieve ('main', etc.)
168
    - modFunct: function, optional - String modification function
169
    
170
    Returns:
171
    Company: Company object with requested information
172
    """
173
```
174

175
**Available Information Sets:**
176
- `'main'` - Basic company information (name, type, location, etc.)
177

178
**Usage Example:**
179

180
```python
181
from imdb import IMDb
182

183
ia = IMDb()
184

185
# Get company with basic info
186
company = ia.get_company('0022125')  # Warner Bros
187
print(f"Company: {company['name']}")
188
print(f"Country: {company.get('country', 'N/A')}")
189

190
# Access company details
191
if 'long imdb name' in company:
192
    print(f"Full name: {company['long imdb name']}")
193
```
194

195
### Company Information Sets
196

197
Get available information sets for company objects.
198

199
```python { .api }
200
def get_company_infoset():
201
    """
202
    Get list of available information sets for companies.
203
    
204
    Returns:
205
    list: Available information set names
206
    """
207
```
208

209
### Company Object Creation
210

211
Create new Company objects with specified parameters.
212

213
```python { .api }
214
def new_company(*arguments, **keywords):
215
    """
216
    Create a new Company object.
217
    
218
    Parameters:
219
    - *arguments: Variable arguments for Company constructor
220
    - **keywords: Keyword arguments for Company constructor
221
    
222
    Returns:
223
    Company: New Company object instance
224
    """
225
```
226

227
## Character Data Structure
228

229
Character objects provide dictionary-like access to character information:
230

231
### Basic Information
232
- `'name'` - Character name
233
- `'long imdb name'` - Full character name as displayed on IMDb
234
- `'canonical name'` - Canonical form of character name
235

236
### Filmography Information
237
- `'filmography'` - List of movies/shows the character appears in
238
- Each entry contains movie information and character details
239

240
**Usage Example:**
241

242
```python
243
from imdb import IMDb
244

245
ia = IMDb()
246

247
# Get comprehensive character information
248
character = ia.get_character('0000196', info='all')
249

250
print(f"Character: {character['name']}")
251
if 'long imdb name' in character:
252
    print(f"Full name: {character['long imdb name']}")
253

254
# Character appearances
255
if 'filmography' in character:
256
    print(f"Appears in {len(character['filmography'])} productions:")
257
    for movie in character['filmography'][:5]:
258
        title = movie['title']
259
        year = movie.get('year', 'N/A')
260
        print(f"  - {title} ({year})")
261
```
262

263
## Company Data Structure
264

265
Company objects provide dictionary-like access to company information:
266

267
### Basic Information
268
- `'name'` - Company name
269
- `'long imdb name'` - Full company name as displayed on IMDb
270
- `'country'` - Country of origin
271
- `'company type'` - Type of company (distributor, production company, etc.)
272

273
### Company Categories
274
Companies are categorized by their role in film production:
275
- Production companies
276
- Distributors
277
- Special effects companies
278
- Miscellaneous companies
279
- And other specialized categories
280

281
**Usage Example:**
282

283
```python
284
from imdb import IMDb
285

286
ia = IMDb()
287

288
# Get comprehensive company information
289
companies = ia.search_company('Disney')
290
company = companies[0]
291
ia.update(company, info='all')
292

293
print(f"Company: {company['name']}")
294
print(f"Country: {company.get('country', 'N/A')}")
295
print(f"Type: {company.get('company type', 'N/A')}")
296

297
if 'long imdb name' in company:
298
    print(f"Full name: {company['long imdb name']}")
299
```
300

301
## Advanced Search and Operations
302

303
### Character-Actor Relationships
304

305
Characters are often linked to the actors who portray them:
306

307
```python
308
from imdb import IMDb
309

310
ia = IMDb()
311

312
# Search for a character
313
characters = ia.search_character('Harry Potter')
314
character = characters[0]
315
ia.update(character, info=['filmography'])
316

317
# Find actors who played this character
318
for movie in character.get('filmography', []):
319
    print(f"In {movie['title']}:")
320
    # Character information often includes actor details
321
    if 'cast' in movie:
322
        for cast_member in movie['cast']:
323
            if character['name'].lower() in str(cast_member).lower():
324
                print(f"  Played by: {cast_member['name']}")
325
```
326

327
### Company Productions
328

329
Find movies produced or distributed by specific companies:
330

331
```python
332
from imdb import IMDb
333

334
ia = IMDb()
335

336
# Search for company
337
companies = ia.search_company('Marvel Studios')
338
company = companies[0]
339

340
# Note: Company filmography requires additional parsing
341
# Company data structure varies by access system
342
print(f"Company: {company['name']}")
343
print(f"Company ID: {company.companyID}")
344

345
# Company information is often found in movie data
346
# Search for movies and check production companies
347
movies = ia.search_movie('Avengers')
348
for movie in movies[:3]:
349
    ia.update(movie, info=['main'])
350
    if 'production companies' in movie:
351
        for prod_company in movie['production companies']:
352
            if 'Marvel' in prod_company['name']:
353
                print(f"{movie['title']} - produced by {prod_company['name']}")
354
```
355

356
## ID Conversion and URLs
357

358
Character and company ID conversion and URL generation:
359

360
```python
361
from imdb import IMDb
362

363
ia = IMDb()
364

365
# Get character
366
character = ia.get_character('0000196')
367

368
# Get IMDb URL for character
369
character_url = ia.get_imdbURL(character)
370
print(f"Character URL: {character_url}")
371

372
# Get company
373
company = ia.get_company('0022125')
374

375
# Get IMDb URL for company
376
company_url = ia.get_imdbURL(company)
377
print(f"Company URL: {company_url}")
378

379
# Convert names to IMDb IDs
380
character_id = ia.character2imdbID('James Bond')
381
company_id = ia.company2imdbID('Warner Bros')
382
```