isic4kit 0.0.5

A Python SDK Library for working with the International Standard Industrial Classification of All Economic Activities (ISIC), Revision 4.

ISIC4Kit

A Python SDK Library for working with the International Standard Industrial Classification of All Economic Activities (ISIC), Revision 4.

Features

• Search and navigate through the ISIC hierarchical structure
• Support for multiple languages (English, Arabic, and more coming soon)
• Pydantic-based
• Easy to use
• Well-documented
• Tested and maintained
• Lightweight and fast

Data Structure

ISIC Hierarchy

ISIC follows a hierarchical structure:

flowchart TD
    Section[Section] --> Division[Division]
    Division --> Group[Group]
    Group --> Class[Class]
    
    Section --> |contains| SectionDesc[Description]
    Division --> |contains| DivisionDesc[Description]
    Group --> |contains| GroupDesc[Description]
    Class --> |contains| ClassDesc[Description]

Each level contains:

• Section: Highest level (A-U), e.g., "A" for Agriculture
• Division: Two-digit code (01-99)
• Group: Three-digit code (011-999)
• Class: Four-digit code (0111-9999)

Data Format

The ISIC data is organized in a hierarchical structure:

sections = [
    {
        "section": "A",
        "description": "Agriculture, forestry and fishing",
        "divisions": [
            {
                "division": "01",
                "description": "Crop and animal production",
                "groups": [
                    {
                        "group": "011",
                        "description": "Growing of non-perennial crops",
                        "classes": [
                            {
                                "class": "0111",
                                "description": "Growing of cereals"
                            },
                            # ...
                        ]
                    },
                    # ...
                ]
            },
            # ...
        ]
    },
    # ...
]

Demo

The following is a demo of the SDK library in action.

Technical Diagrams

ISIC4 Hierarchy Structure

classDiagram
    ISICSection "1" --> "*" ISICDivision : contains
    ISICDivision "1" --> "*" ISICGroup : contains
    ISICGroup "1" --> "*" ISICClass : contains

    class ISICSection {
        +str code
        +str description
        +List[ISICDivision] divisions
        +print_tree()
    }
    
    class ISICDivision {
        +str code
        +str description
        +List[ISICGroup] groups
        +print_tree()
    }
    
    class ISICGroup {
        +str code
        +str description
        +List[ISICClass] classes
        +print_tree()
    }
    
    class ISICClass {
        +str code
        +str description
        +print_tree()
    }

ISIC4Kit Search Sequence

sequenceDiagram
    participant User
    participant ISIC4Classifier
    participant ISICSearchMixin
    participant Models
    participant Tree

    User->>ISIC4Classifier: search(query)
    activate ISIC4Classifier
    
    ISIC4Classifier->>ISICSearchMixin: search(query)
    activate ISICSearchMixin
    
    ISICSearchMixin->>ISICSearchMixin: process query
    ISICSearchMixin->>Models: create ISICSearchResult
    activate Models
    Models-->>ISICSearchMixin: return result
    deactivate Models
    
    ISICSearchMixin->>Models: create ISICSearchResults
    activate Models
    Models-->>ISICSearchMixin: return results
    deactivate Models
    
    ISICSearchMixin-->>ISIC4Classifier: return results
    deactivate ISICSearchMixin
    
    ISIC4Classifier->>Tree: print_tree()
    activate Tree
    Tree-->>ISIC4Classifier: display hierarchy
    deactivate Tree
    
    ISIC4Classifier-->>User: return formatted results
    deactivate ISIC4Classifier

ISIC4Kit Component Architecture

flowchart TB
    subgraph Main
        ISIC4Classifier
    end

    subgraph Base Classes
        BaseISIC4
        ISICSearchMixin
        ISICLoaderMixin
    end

    subgraph Models
        ISICSection
        ISICDivision
        ISICGroup
        ISICClass
        ISICHierarchy
        ISICSearchResult
        ISICSearchResults
    end

    subgraph Utils
        Tree
    end

    ISIC4Classifier --> BaseISIC4
    ISIC4Classifier --> ISICSearchMixin
    ISIC4Classifier --> ISICLoaderMixin
    
    BaseISIC4 --> ISICSection
    BaseISIC4 --> ISICDivision
    BaseISIC4 --> ISICGroup
    BaseISIC4 --> ISICClass
    
    ISICSearchMixin --> ISICSearchResult
    ISICSearchMixin --> ISICSearchResults
    ISICSearchMixin --> ISICHierarchy
    
    ISICSection --> Tree
    ISICDivision --> Tree
    ISICGroup --> Tree
    ISICClass --> Tree

Installation

Poetry (recommended)

poetry add isic4kit

pip

pip install isic4kit

Dependencies

• Python >=3.8, <4.0
• pydantic ^2.10.6
• pytest ^8.3.4

Usage

Basic Usage

from isic4kit import ISIC4Classifier

# Initialize classifier (English)
isic_en = ISIC4Classifier(language="en")

# Example 1: Get section (Agriculture)
section = isic_en.get_section("a")
# Access divisions directly
for division in section.divisions:
    print(division.code, division.description)
    # Access groups
    for group in division.groups:
        print(group.code, group.description)
        # Access classes
        for class_ in group.classes:
            print(class_.code, class_.description)
# Or use the tree visualization
section.print_tree()

# Example 2: Get division (Crop and animal production)
division = isic_en.get_division("01")
division.print_tree()

# Example 3: Get group (Growing of non-perennial crops)
group = isic_en.get_group("011")
group.print_tree()

# Example 4: Get class (Growing of cereals)
class_ = isic_en.get_class("0111")
class_.print_tree()

Search Functionality

# Search for activities containing "mining"
results = isic_en.search("mining")
results.print_tree()

Multi-language Support

The classifier supports multiple languages. Here's an example in Arabic:

# Initialize with Arabic language
isic_ar = ISIC4Classifier(language="ar")

# Example 1: Get section (الزراعة)
section_ar = isic_ar.get_section("a")
section_ar.print_tree()

# Example 2: Get division (زراعة المحاصيل والإنتاج الحيواني)
division_ar = isic_ar.get_division("01")
division_ar.print_tree()

# Example 3: Get group (زراعة المحاصيل غير الدائمة)
group_ar = isic_ar.get_group("011")
group_ar.print_tree()

# Example 4: Get class (زراعة الحبوب)
class_ar = isic_ar.get_class("0111")
class_ar.print_tree()

# Example 5: Search in Arabic
search_ar = isic_ar.search("تعدين")
search_ar.print_tree()

Examples

English Examples

from isic4kit import ISIC4Classifier

# Initialize English classifier
isic_en = ISIC4Classifier(language="en")

# Example 1: Get section (Agriculture)
section_en = isic_en.get_section("a")
section_en.print_tree()

Output:

└── a: Agriculture, forestry and fishing
    ├── 01: Crop and animal production, hunting and related service activities
    │   ├── 011: Growing of non-perennial crops
    │   │   ├── 0111: Growing of cereals (except rice), leguminous crops and oil seeds
    │   │   ├── 0112: Growing of rice
    │   │   ├── 0113: Growing of vegetables and melons, roots and tubers
    │   │   ├── 0114: Growing of sugar cane
    │   │   ├── 0115: Growing of tobacco
    │   │   ├── 0116: Growing of fibre crops
    │   │   └── 0119: Growing of other non-perennial crops
    │   └── ...
    ├── 02: Forestry and logging
    └── 03: Fishing and aquaculture

# Example 2: Get division (Crop and animal production)
division_en = isic_en.get_division("01")
division_en.print_tree()

Output:

└── 01: Crop and animal production, hunting and related service activities
    ├── 011: Growing of non-perennial crops
    │   ├── 0111: Growing of cereals (except rice), leguminous crops and oil seeds
    │   ├── 0112: Growing of rice
    │   ├── 0113: Growing of vegetables and melons, roots and tubers
    │   ├── 0114: Growing of sugar cane
    │   ├── 0115: Growing of tobacco
    │   ├── 0116: Growing of fibre crops
    │   └── 0119: Growing of other non-perennial crops
    └── ...

# Example 3: Get group (Growing of non-perennial crops)
group_en = isic_en.get_group("011")
group_en.print_tree()

Output:

└── 011: Growing of non-perennial crops
    ├── 0111: Growing of cereals (except rice), leguminous crops and oil seeds
    ├── 0112: Growing of rice
    ├── 0113: Growing of vegetables and melons, roots and tubers
    ├── 0114: Growing of sugar cane
    ├── 0115: Growing of tobacco
    ├── 0116: Growing of fibre crops
    └── 0119: Growing of other non-perennial crops

# Example 4: Get class (Growing of cereals)
class_en = isic_en.get_class("0111")
class_en.print_tree()

Output:

└── 0111: Growing of cereals (except rice), leguminous crops and oil seeds

# Example 5: Search in English
search_en = isic_en.search("mining")
search_en.print_tree()

Output:

├── 05: Mining of coal and lignite
│   ├── 051: Mining of hard coal
│   │   ├── 0510: Mining of hard coal (anthracite)
│   ├── 052: Mining of lignite
│   │   ├── 0520: Mining of lignite
├── 07: Mining of metal ores
│   ├── 071: Mining of iron ores
│   │   ├── 0710: Mining of iron ores
│   ├── 072: Mining of non-ferrous metal ores
│   │   ├── 0721: Mining of uranium and thorium ores
│   │   ├── 0729: Mining of other non-ferrous metal ores
├── 08: Other mining and quarrying
│   ├── 089: Mining and quarrying n.e.c.
│   │   ├── 0891: Mining of chemical and fertilizer minerals
│   │   ├── 0899: Other mining and quarrying n.e.c.
├── 09: Mining support service activities
│   ├── 099: Support activities for other mining and quarrying
│   │   ├── 0990: Support activities for other mining and quarrying
│   │   ├── 2824: Manufacture of machinery for mining, quarrying and construction

Arabic Examples

# Initialize Arabic classifier
isic_ar = ISIC4Classifier(language="ar")

# Example 1: Get section (الزراعة)
section_ar = isic_ar.get_section("a")
section_ar.print_tree()

Output:

└── a: الزراعة والحراجة وصيد الأسماك
    ├── 01: أنشطة زراعة المحاصيل والإنتاج الحيواني والصيد والخدمات المتصلة
    │   ├── 011: زراعة المحاصيل غير الدائمة
    │   │   ├── 0111: زراعة الحبوب باستثناء الأرز( والمحاصيل البقولية والبذور الزيتية)
    │   │   └── ...
    └── ...

# Example 5: Search in Arabic
search_ar = isic_ar.search("تعدين")
search_ar.print_tree()

Output:

├── 05: تعدين الفحم والليغنيت
│   ├── 051: تعدين الفحم القاسي (الأنفراثيت)
│   │   ├── 0510: تعدين الفحم القاسي (الأنفراثيت)
│   ├── 052: تعدين الليغنيت
│   │   ├── 0520: تعدين الليغنيت
├── 07: تعدين ركازات الفلزات
│   ├── 071: تعدين ركازات الحديد
│   │   ├── 0710: تعدين ركازات الحديد
│   └── ...
└── ...

Supported Languages

• English (en)
• Arabic (ar)
• More languages coming soon...

Development Setup

# Clone the repository
git clone https://github.com/anqorithm/isic4kit.git
cd isic4kit

# Install poetry (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install

# Activate virtual environment
poetry shell

Testing

Run the test suite using pytest:

# Run all tests
poetry run pytest

Coverage

The test suite includes unit tests for all classes and methods. The coverage report can be generated using the following command:

poetry run pytest --cov=isic4kit tests/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Contributors

• Abdullah Alqahtani

References

1. United Nations Statistics Division. (2008). International Standard Industrial Classification of All Economic Activities (ISIC), Revision 4. English Version

2. United Nations Statistics Division. (2008). التصنيف الصناعي الدولي الموحد لجميع الأنشطة الاقتصادية، التنقيح 4. Arabic Version

3. Ministry of Commerce - Saudi Arabia. (2023). ISIC4 Guide. Source

4. Saudi Food and Drug Authority. (2023). Economic Activities Classification. Source

5. General Authority for Statistics - Saudi Arabia. (2023). ISIC4 Classification. Source

License

MIT License