Migration Guide

This guide will help you migrate between different versions of countryflag.

Migrating to v1.1.1 from v1.0.1

Cache Singleton Behavior (Breaking Change)

Version 1.1.1 enhances the automatic cache sharing feature introduced in v1.0.1 across CountryFlag instances.

What Changed:

# Before v1.0.1
cf1 = CountryFlag()  # No caching (cache=None)
cf2 = CountryFlag()  # No caching (cache=None)

# From v1.0.1 onwards (enhanced in v1.1.1)
cf1 = CountryFlag()  # Automatic global cache sharing
cf2 = CountryFlag()  # Same global cache as cf1

Impact:

  • Performance Improvement: Instances now automatically benefit from shared caching

  • Memory Efficiency: Single cache instance reduces memory usage

  • Thread Safety: Enhanced with proper locking mechanisms

  • Backward Compatibility: Existing code continues to work unchanged

Migration Steps:

  1. No code changes required - existing applications will automatically benefit

  2. Test cache behavior - if your tests depend on no caching, use CountryFlag.clear_global_cache()

  3. Monitor performance - expect significant improvements in repeated operations

For Testing Code:

import unittest
from countryflag.core import CountryFlag

class MyTest(unittest.TestCase):
    def setUp(self):
        # Clear global cache before each test
        CountryFlag.clear_global_cache()

    def test_something(self):
        cf = CountryFlag()
        # Test code here

Disabling Global Cache (if needed):

from countryflag.cache.base import NoOpCache

# Create instance with no caching (pre-v1.0.1 behavior)
cf = CountryFlag(cache=NoOpCache())

Migrating to v1.0.0 from v0.2.0

Version 1.0.0 is primarily focused on production readiness and deployment features. Most API changes are additive.

Migrating to v0.2.0 from v0.1.x

Overview of Changes

Version 0.2.0 is a major update with significant improvements:

  • Complete restructuring of the package architecture

  • New caching system for improved performance

  • Support for region-based lookups

  • Enhanced command-line interface

  • Many performance improvements and bug fixes

Breaking Changes

While we’ve tried to maintain backward compatibility, there are a few breaking changes:

  1. The getflag() function now returns a tuple (flags, pairs) when used from the API. The first element is the flags string (same as before), and the second element is a list of (country, flag) pairs.

  2. Some command-line arguments have changed or been added.

  3. Error handling has been improved with specific exception types.

Updating Code

Basic usage remains compatible:

# Old code (still works)
import countryflag
flags = countryflag.getflag(['Germany', 'France', 'Italy'])
print(flags)  # 🇩🇪 🇫🇷 🇮🇹

# New code with additional features
import countryflag
flags, pairs = countryflag.getflag(['Germany', 'France', 'Italy'])
print(flags)  # 🇩🇪 🇫🇷 🇮🇹
print(pairs)  # [('Germany', '🇩🇪'), ('France', '🇫🇷'), ('Italy', '🇮🇹')]

Using the Enhanced API

The new version provides a more powerful API through the CountryFlag class:

from countryflag.core import CountryFlag

# Create a CountryFlag instance
cf = CountryFlag()

# Convert country names to flags
flags, pairs = cf.get_flag(['Germany', 'France', 'Italy'])

# Format output in different formats
json_output = cf.format_output(pairs, output_format='json')
csv_output = cf.format_output(pairs, output_format='csv')

# Reverse lookup (flag to country)
flag_country_pairs = cf.reverse_lookup(['🇩🇪', '🇫🇷', '🇮🇹'])

# Get flags for all countries in a region
europe_flags, europe_pairs = cf.get_flags_by_region('Europe')

Using Caching

One of the biggest performance improvements in v0.2.0 is the caching system:

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

# In-memory caching
memory_cache = MemoryCache()
cf = CountryFlag(cache=memory_cache)

# Persistent disk caching
disk_cache = DiskCache('/path/to/cache/dir')
cf = CountryFlag(cache=disk_cache)

# Subsequent calls with the same inputs will be much faster
flags, pairs = cf.get_flag(['Germany', 'France', 'Italy'])

Error Handling

The new version uses custom exceptions for better error handling:

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

cf = CountryFlag()

try:
    flags, pairs = cf.get_flag(['Germany', 'Invalid Country'])
except InvalidCountryError as e:
    print(f"Error: {e}")
    print(f"Invalid country: {e.country}")

Command Line Interface

The command-line interface has been enhanced with many new options:

# Basic usage (unchanged)
countryflag Germany France Italy

# New options
countryflag --format json Germany France Italy  # Output as JSON
countryflag --separator "|" Germany France Italy  # Custom separator
countryflag --fuzzy Germny Frnce Itly  # Fuzzy matching
countryflag --region Europe  # Get all European country flags
countryflag --interactive  # Interactive mode with autocompletion
countryflag --reverse 🇩🇪 🇫🇷 🇮🇹  # Reverse lookup
countryflag --file countries.txt  # Read from file
countryflag --cache  # Enable caching

Performance Considerations

See the Performance Optimization Guide guide for detailed information on optimizing performance in v0.2.0.

Final Notes

If you encounter any issues migrating to v0.2.0, please report them on the GitHub issue tracker.