Quickstart Guide

This quickstart guide will help you get up and running with CountryFlag quickly.

Installation

Install CountryFlag using pip:

pip install countryflag

Basic Usage

Converting Country Names to Flags

The simplest way to use CountryFlag is to import the package and use the getflag() function:

import countryflag

# Convert a list of country names to emoji flags
flags = countryflag.getflag(['Germany', 'France', 'Italy'])
print(flags)  # 🇩🇪 🇫🇷 🇮🇹

# Use different separators
flags = countryflag.getflag(['Germany', 'France', 'Italy'], separator='|')
print(flags)  # 🇩🇪|🇫🇷|🇮🇹

The getflag() function accepts various country name formats:

# ISO-2 codes
flags = countryflag.getflag(['DE', 'FR', 'IT'])
print(flags)  # 🇩🇪 🇫🇷 🇮🇹

# ISO-3 codes
flags = countryflag.getflag(['DEU', 'FRA', 'ITA'])
print(flags)  # 🇩🇪 🇫🇷 🇮🇹

# Full names
flags = countryflag.getflag(['Germany', 'France', 'Italy'])
print(flags)  # 🇩🇪 🇫🇷 🇮🇹

# Mixed formats
flags = countryflag.getflag(['Germany', 'FR', 'ITA'])
print(flags)  # 🇩🇪 🇫🇷 🇮🇹

Using the CountryFlag Class

For more advanced usage, you can use the CountryFlag class directly:

from countryflag.core import CountryFlag

# Create a CountryFlag instance
cf = CountryFlag()

# Convert country names to flags
flags, pairs = cf.get_flag(['Germany', 'France', 'Italy'])
print(flags)  # 🇩🇪 🇫🇷 🇮🇹
print(pairs)  # [('Germany', '🇩🇪'), ('France', '🇫🇷'), ('Italy', '🇮🇹')]

# Format output as JSON
json_output = cf.format_output(pairs, output_format='json')
print(json_output)
# [{"country": "Germany", "flag": "🇩🇪"}, {"country": "France", "flag": "🇫🇷"}, {"country": "Italy", "flag": "🇮🇹"}]

Reverse Lookup

You can also convert flag emojis back to country names:

from countryflag.core import CountryFlag

cf = CountryFlag()
pairs = cf.reverse_lookup(['🇩🇪', '🇫🇷', '🇮🇹'])
print(pairs)  # [('🇩🇪', 'Germany'), ('🇫🇷', 'France'), ('🇮🇹', 'Italy')]

Region-Based Lookup

Get flags for all countries in a specific region:

from countryflag.core import CountryFlag

cf = CountryFlag()

# Get all European country flags
flags, pairs = cf.get_flags_by_region('Europe')
print(f"Found {len(pairs)} European countries")
print(flags)  # All European country flags

Command Line Usage

CountryFlag can be used from the command line in two equivalent ways:

Positional Arguments (Short Form):

# Basic usage
countryflag Germany France Italy

# Custom separator
countryflag --separator "|" Germany France Italy

# JSON output
countryflag --format json Germany France Italy

Named Arguments (Explicit Form):

# Basic usage
countryflag --countries Germany France Italy

# Custom separator
countryflag --separator "|" --countries Germany France Italy

# JSON output
countryflag --format json --countries Germany France Italy

Other Commands (Both Forms Support These Options):

# Reading from a file
countryflag --file countries.txt

# Get flags for a region
countryflag --region Europe

# Interactive mode
countryflag --interactive

Note

Both positional and named argument forms are equivalent and produce the same output. The positional form is shorter, while the named form is more explicit and may be preferred in scripts.

Common Use Cases

Handling Invalid Country Names

Use fuzzy matching to handle slightly misspelled country names:

from countryflag.core import CountryFlag
from countryflag.core.exceptions import InvalidCountryError

cf = CountryFlag()

try:
    flags, pairs = cf.get_flag(['Germny', 'Frnce', 'Itly'], fuzzy_matching=True)
    print(flags)  # 🇩🇪 🇫🇷 🇮🇹
except InvalidCountryError as e:
    print(f"Error: {e}")

Caching for Performance

Use caching to improve performance for repeated lookups:

from countryflag.core import CountryFlag
from countryflag.cache import MemoryCache

# Create a memory cache
cache = MemoryCache()

# Create a CountryFlag instance with caching
cf = CountryFlag(cache=cache)

# First lookup (cache miss)
flags1, pairs1 = cf.get_flag(['Germany', 'France', 'Italy'])

# Second lookup (cache hit - much faster)
flags2, pairs2 = cf.get_flag(['Germany', 'France', 'Italy'])

For persistent caching, use DiskCache:

from countryflag.core import CountryFlag
from countryflag.cache import DiskCache

# Create a disk cache
cache = DiskCache("/path/to/cache/dir")

# Create a CountryFlag instance with disk caching
cf = CountryFlag(cache=cache)

File Processing

Process country names from a file:

from countryflag.utils.io import process_file_input
from countryflag.core import CountryFlag

# Read country names from a file
countries = process_file_input("countries.txt")

# Convert to flags
cf = CountryFlag()
flags, pairs = cf.get_flag(countries)
print(flags)

For large files, use asynchronous processing:

import asyncio
from countryflag.utils.io import process_file_input_async
from countryflag.core import CountryFlag

async def process_large_file():
    # Read country names from a file asynchronously
    countries = await process_file_input_async("large_file.txt")

    # Convert to flags
    cf = CountryFlag()
    flags, pairs = cf.get_flag(countries)
    print(flags)

asyncio.run(process_large_file())

Best Practices

  1. Reuse CountryFlag Instances

    Create a single CountryFlag instance and reuse it:

    # Good
cf = CountryFlag()
flags1, _ = cf.get_flag(['Germany', 'France'])
flags2, _ = cf.get_flag(['Italy', 'Spain'])

# Bad (creates multiple instances)
flags1, _ = CountryFlag().get_flag(['Germany', 'France'])
flags2, _ = CountryFlag().get_flag(['Italy', 'Spain'])

  2. Use Caching for Repeated Lookups

    Enable caching for improved performance:

    from countryflag.cache import MemoryCache

cache = MemoryCache()
cf = CountryFlag(cache=cache)

  3. Process in Batches

    For large datasets, process in batches:

    def process_large_list(countries, batch_size=500):
    cf = CountryFlag()
    result_pairs = []

    for i in range(0, len(countries), batch_size):
        batch = countries[i:i+batch_size]
        _, pairs = cf.get_flag(batch)
        result_pairs.extend(pairs)

    return result_pairs

  4. Handle Errors Gracefully

    Catch and handle exceptions:

    from countryflag.core.exceptions import InvalidCountryError

try:
    flags, pairs = cf.get_flag(['Germany', 'InvalidCountry'])
except InvalidCountryError as e:
    print(f"Error: {e}")
    # Handle the error or use fuzzy matching
    flags, pairs = cf.get_flag(['Germany'], fuzzy_matching=True)

  5. Use Proper Output Formats

    Choose the appropriate output format for your needs:

    # For display to users
text_output = cf.format_output(pairs, output_format='text')

# For APIs
json_output = cf.format_output(pairs, output_format='json')

# For data processing
csv_output = cf.format_output(pairs, output_format='csv')

Performance Tips

  1. Use Memory Caching for Speed

    Memory caching offers the best performance:

    from countryflag.cache import MemoryCache

cache = MemoryCache()
cf = CountryFlag(cache=cache)

  2. Use Disk Caching for Persistence

    Disk caching provides persistence across runs:

    from countryflag.cache import DiskCache

cache = DiskCache("/path/to/cache/dir")
cf = CountryFlag(cache=cache)

  3. Use Parallel Processing for Large Datasets

    Process large datasets in parallel:

    import concurrent.futures

def process_in_parallel(countries, num_workers=4):
    chunks = [countries[i:i+500] for i in range(0, len(countries), 500)]
    results = []

    with concurrent.futures.ThreadPoolExecutor(max_workers=num_workers) as executor:
        futures = [executor.submit(process_chunk, chunk) for chunk in chunks]
        for future in concurrent.futures.as_completed(futures):
            results.extend(future.result())

    return results

def process_chunk(chunk):
    cf = CountryFlag()
    _, pairs = cf.get_flag(chunk)
    return pairs

  4. Remove Duplicates

    Remove duplicate country names before processing:

    # Remove duplicates to avoid redundant processing
unique_countries = list(set(countries))
flags, pairs = cf.get_flag(unique_countries)

  5. Use Asynchronous Processing for I/O-Bound Operations

    Use async/await for I/O-bound operations:

    import asyncio

async def process_files(file_paths):
    from countryflag.utils.io import process_file_input_async

    tasks = [process_file_input_async(file_path) for file_path in file_paths]
    results = await asyncio.gather(*tasks)

    # Flatten the results
    countries = [country for sublist in results for country in sublist]

    return countries

Next Steps

Now that you’ve got the basics, check out these guides for more advanced usage: