Chapter 2 — Library classes

Defining library classes
Library classes are pre-written, reusable classes supplied as part of a language's modules or as separately distributed packages. Each class groups related data (attributes) and behaviour (methods) so programmers can create and use objects without implementing common logic from scratch. Instead of writing low-level code for file handling, dates or data structures, you instantiate and call methods on library classes to perform tasks quickly.

Why they matter for school projects
For Class 10 projects, library classes let you focus on the problem domain rather than low-level details. For example, a date class helps calculate ages, while a CSV reader saves time when working with tabular marks. Using libraries leads to more reliable programs because these classes are tested and used widely.

How library classes are organised
Libraries are organised into modules and packages. A module is a single file containing related classes and functions. A package is a folder grouping several modules. Standard libraries come bundled with the language; third-party libraries are installed separately. User-defined modules are those you create and import into other projects.

Benefits and trade-offs
Major benefits include code reuse, better maintainability, and time savings. Trade-offs are dependency management, learning a new API, and sometimes licensing considerations. For small assignments, favour standard libraries to reduce installation issues. For advanced needs, well-documented third-party libraries can be chosen carefully.

Practical behaviours
When using library classes, check constructor parameters and method names from documentation, expect certain return types, and learn which exceptions may be raised. Keep imports clear and prefer small helper wrappers if a library's API is complex. Document how you used the library in your project's README so teachers and peers can run your work.

Summary
Library classes are essential building blocks of modern programming. They enable students to build useful, reliable programs more quickly by reusing tested code while learning better design and documentation practices.

Understanding the two types
The standard library is the collection of modules and classes that are included with the language installation. These are maintained by the language's core team and designed to be stable and portable across platforms. Third-party libraries are written and maintained by external developers or organisations and are typically installed using a package manager. They can provide specialised features not available in the standard library.

Benefits of the standard library
Because standard library modules come bundled, there is no need for extra installation, which simplifies sharing school projects. Standard modules are well-documented, commonly tested on many platforms, and designed for general purposes. This makes them a safe first choice when solving problems like file handling, basic data structures, simple HTTP requests or date arithmetic.

Advantages of third-party libraries
Third-party libraries can be more feature-rich and optimized for specific domains: graphics, numerical computing, web scraping, or advanced machine learning. They often offer convenient high-level functions that save time in complex tasks. Active communities can provide examples, tutorials and bug fixes.

Risks and trade-offs
Using third-party libraries means dealing with dependencies, version compatibility and sometimes licensing restrictions. Libraries may change APIs between versions, causing programs to break if not updated together with their dependencies. For class work, these risks can be mitigated by pinning versions and providing clear installation instructions.

How to choose between them

• First check if the standard library already solves the problem—prefer it for portability.
• If not, evaluate third-party options for documentation quality, community activity, licence type and stability.
• Pick libraries with permissive licences for sharing and with minimal additional dependencies.

Practical steps when using third-party libraries

• Record the exact version used in a requirements file so others can reproduce your environment.
• Test your code in a clean environment or virtual environment to ensure it works without extra global packages.
• Include simple installation commands in your README for classmates and teachers.

Summary
Standard libraries provide dependable building blocks suitable for most school projects; third-party libraries expand capability but require careful management. Learning to decide and manage dependencies is an important skill for reliable programming.

Purpose of import
Importing is how a program gains access to code defined in another file or package. Imports let you use classes, functions and constants defined elsewhere without copying their source. Understanding import forms and rules helps keep code clear and avoids naming conflicts.

Common import forms
There are three common patterns used in many languages. First, importing the full module (import module_name) keeps the module's namespace explicit; you refer to items as module_name.Class or module_name.function. Second, importing specific items (from module_name import ClassName) lets you use ClassName directly without the module prefix. Third, aliasing (import module_name as alias) shortens long module names and clarifies intent when used consistently.

Choosing an import style

• Use full module imports when you want to show clearly where each function or class comes from.
• Use specific imports when you need several names repeatedly and want concise code.
• Avoid wildcard imports (import *) because they clutter the namespace and can overwrite existing names.

Module search path
The interpreter looks for modules in a sequence of folders: the current directory, standard library paths, and any additional paths configured in the environment. When importing your own modules, place them in the same folder as the program or in a package structure so the interpreter can find them. Understanding the search path helps debug ImportError problems.

Handling import errors
If an import fails, first check the module name spelling and ensure the module file exists in the search path. For third-party libraries, confirm installation in the same environment you run the program. In classroom setups, prefer keeping library files within the project folder to avoid environment mismatch.

Organising imports
Place import statements at the top of the file for clarity. Group related imports together (standard library first, then third-party, then local modules) and add short comments when imports are non-obvious. This makes the code easier to read and maintain for both you and your teacher.

Practical tips
When sharing code, include simple instructions on how to install required third-party modules or include the module files with your submission. Keep names consistent and avoid creating files with the same name as standard modules to prevent shadowing.

Identifying useful classes
The standard library contains many classes that solve common problems. Examples include file objects for reading and writing, date/time classes for handling dates and intervals, collections for specialised data containers, and math utilities for calculations. Learn which classes are relevant to your tasks so you can build solutions efficiently.

Typical usage pattern
To use a standard library class: import the module, examine the constructor signature, create an instance and call its methods; or use class or static methods if provided. Always check what types methods return (string, number, list) and whether they modify the object or return new values. This understanding avoids bugs due to unexpected side effects.

File handling example
File objects let you open files in various modes: read, write or append. Using context managers (if available) or proper closing ensures resources are released. When reading line-based records, iterate over the file object which yields each line; when writing, ensure you encode or format data according to the chosen file format (text, CSV, JSON).

Date and time
Date classes let you parse strings, format dates for display, and compute differences—useful for calculating age, durations or sorting records chronologically. Be mindful of formats and always convert strings into date objects before arithmetic.

Collections and data structures
Standard collections offer queues, deques, and default maps that simplify code and improve performance. For example, use a deque for efficient additions/removals at both ends or a default dictionary to avoid checking for missing keys. Choosing the right structure can greatly reduce code complexity.

Performance and limits
Standard classes balance generality and performance. For large data sets, consider streaming data (process line by line) instead of loading everything into memory. Check documentation for algorithmic behaviour (sorting, searching) when performance matters.

Read the examples
Documentation often includes examples—copy and run these snippets to learn how a class behaves. Practise small programs that combine two or more standard classes to solve real tasks such as mark-sheet generation or attendance tracking.

When to create a module
If you find yourself copying the same functions or classes between programs, it is time to extract them into a reusable module. This reduces duplication and centralises fixes: change once and all programs using the module benefit. For Class 10, simple modules for reading marks, validating input or handling student records are practical examples.

Module structure and naming
A module is a single file that groups related code. Choose a clear file name that reflects its purpose, e.g. student_utils.py. Inside the module, include related classes and helper functions. Keep function and class names descriptive and avoid very long files—split code into multiple modules by concern (e.g., file_io.py, data_models.py).

Designing reusable classes
Design classes with clear responsibilities: a Student class should store data and provide methods like compute_average() or to_dict(). Keep constructors simple and provide defaults when appropriate. Avoid printing directly from class methods; return values so calling code decides how to present data. This separation improves testability and reuse.

Documentation and examples
Add docstrings at the top of the module and for each class/method. Show short examples that other students can copy. Also include a README with installation or placement instructions and a simple usage snippet. Good examples accelerate understanding and reduce questions during assessment.

Packaging for easy import
Place your module file in the same folder as student programs, or arrange modules into a package folder with an __init__ file if you have multiple modules. For class sharing, compress the package folder and include instructions about where to place it so imports work correctly.

Versioning and change management
Give the module a version string and update it when making non-backward-compatible changes. Keep a small changelog to explain what changed. When other classmates depend on your module, communicate changes so they can update their projects if necessary.

Testing locally
Create example scripts that import your module and exercise its functions. Include tests for normal and edge cases. This gives confidence that the module behaves as expected before sharing it.

Core object-oriented ideas
Good library classes follow object-oriented principles that make code modular and maintainable. Encapsulation keeps internal details private and exposes a simple public interface. Abstraction presents a high-level view hiding complex operations. Inheritance allows building specialised classes from general ones, while composition builds objects by combining smaller objects—prefer composition when behaviour can be achieved by using other classes rather than extending them unnecessarily.

Single Responsibility Principle
Each class should have one clear responsibility. If a class both stores data and manages file I/O, split it: one class models the data and another handles persistence. This separation makes classes easier to test and reuse. For Class 10, a Student class should focus on student data and calculations; a separate FileHandler class should handle reading and writing student records.

Designing constructors and methods
Keep constructors simple: require only essential data and provide defaults for optional information. Avoid constructors that do heavy processing or require complex objects; prefer factory methods when object creation needs multiple steps. Methods should perform single, documented tasks and return consistent types. Avoid methods with side effects like printing unless explicitly intended.

Mutable versus immutable objects
Decide whether instances should be mutable (can be changed after creation) or immutable. Immutable objects are safer because they do not change state unexpectedly; use them for value types like Date or Point. Mutable objects are suitable for collections or models that represent changing state. Document the choice clearly so users do not rely on wrong assumptions.

Error handling and validation
Validate inputs in constructors and key methods; raise clear and specific exceptions for invalid data so calling code can handle them. Document which exceptions a method might raise. Avoid catching too many exceptions inside the class—let the caller decide how to respond if appropriate.

Interface simplicity and backward compatibility
Expose a small, stable public interface. When making changes that break the interface, bump the version and document the change. Providing small wrapper methods that hide internal changes helps preserve compatibility for users of your library.

Testing and examples
Write unit tests for each public method and include short examples in documentation. Tests confirm the class follows the contract you defined and catch regressions when you modify code later.

Why documentation matters
Documentation explains how to use your library classes and is essential for reuse. For classmates and teachers to run your project, clear documentation saves time and reduces confusion. In-code documentation (docstrings) and external README files together provide both quick reference and step-by-step guidance.

What to include in docstrings
Every module, class and public method should have a short docstring. A useful docstring contains: a one-line summary of purpose, parameter names and expected types, what the method returns and its type, exceptions that may be raised, and a short usage example. Keep examples minimal and executable so users can copy-paste them to test behaviour.

README and project-level docs
Create a README file at the top level of your project that explains purpose, prerequisites, installation or placement instructions, and a few usage examples. Note the versions of any external libraries used. If your library needs special steps to run, provide step-by-step commands to help others reproduce your environment. Include contact information or a note about allowed use if relevant.

Using external documentation
When you use standard or third-party libraries, learn to read their documentation to find constructors, methods and examples. Start with the overview and quick start, then look at reference pages for specific methods. Use search or index pages to find examples and common usage patterns. Interactive help in a programming shell can show docstrings and list available methods when internet access is unavailable.

Writing examples as tests
Well-written examples double as lightweight tests. Include example scripts that import your module and execute common tasks, printing expected and actual results. This assists teachers to verify outputs quickly and shows that your library works as intended.

Style and clarity
Write short sentences, use consistent terminology and avoid implementation details in public documentation. Focus on what the user should provide and what they will get back. Update documentation when you change the code; mismatched docs cause confusion.

Automated documentation tools
Some languages support tools that generate formatted docs from docstrings. For Class 10 projects, simple docstrings and a README are sufficient. Include sample commands and expected output so others can validate the library easily.

Why exceptions occur
Library calls can fail for many reasons: invalid input, missing files, incorrect formats, permission errors, or network failures. Libraries typically signal these problems by raising exceptions. Handling such exceptions makes programs robust and prevents abrupt crashes during runtime, especially in interactive projects used by classmates or teachers.

Types of exception handling
Basic handling uses try-except blocks to intercept exceptions. Catch specific exception types rather than a broad catch-all to avoid hiding programming errors. Use finally to perform clean-up tasks like closing files. If the language supports context managers (with statements), prefer them because they ensure resources are released even when errors occur.

Design choices: handle or propagate
A function should handle errors it can reasonably fix—for example supply a default file when none is found—or validate input before calling a library method to prevent errors. If the function cannot handle the error meaningfully, it should allow the exception to propagate with a clear message so higher-level code can decide how to present it to the user.

Wrapping exceptions
When building library classes, convert low-level exceptions into higher-level ones that match your module's abstraction. For example, a FileNotFoundError raised while loading student records could be wrapped into DataLoadError with an explanatory message. This approach helps users of your module react appropriately without needing to know internal details.

User-friendly messages and logging
For interactive programs, show user-friendly messages explaining the problem and possible remedies. For debugging or automated runs, log technical details to a log file while presenting simplified messages to the user. Avoid printing stack traces to end users in a classroom submission; include them in logs or make them available on request.

Testing exception paths
Create tests that deliberately trigger exceptions to ensure they are handled as intended. For example, test opening a non-existent file and verify the function either creates a default file or raises the documented exception. Demonstrating controlled error handling strengthens your project and shows foresight to teachers.

Summary
Thoughtful exception handling improves reliability and user experience. Prefer specific catches, clear messages, resource cleanup and documented behaviour for exceptional conditions.

Purpose of tests
Testing ensures that library classes behave as documented and keeps code reliable as it changes. Tests serve both to check correctness and to demonstrate usage for others. For Class 10 projects, a mix of simple unit tests and example scripts is sufficient to show that the library works as intended.

Types of tests
Unit tests focus on single methods or functions, verifying normal and edge-case behaviour. Integration tests check interactions between modules, for example reading a CSV and converting rows into Student objects. Example-based tests are scripts that execute typical tasks and print results for manual verification.

Writing simple unit tests
Start with small functions: call the function with known inputs and compare the returned value to the expected result. For example, verify that compute_average([80,90,70]) returns 80. Include tests that check edge cases such as empty lists, invalid inputs and boundary values. If a method should raise an exception for invalid data, include a test asserting that the exception is raised.

Automating tests
While full test frameworks may be advanced, beginners can create a test file that calls functions and prints pass/fail messages. For each test case, show the expected and actual output. As skills progress, learn a unit test framework to automate running many tests easily.

Using examples as tests
Example scripts in docstrings can be runnable and act as informal tests. Provide a short example for each public method that demonstrates typical usage. When reviewers run the example, they verify behaviour quickly without reading the code deeply.

Test data and reproducibility
Include small sample input files used by tests (e.g., a sample CSV of student marks). Keep test data simple and small so tests run quickly. Document how to run tests and what output to expect in the README.

Benefits of testing
Tests catch bugs early, document expected behaviour, and make refactoring safer. For assessments, tests also prove that your library meets its specification and works under expected conditions.

What packaging achieves
Packaging prepares code so others can use it easily. For small class projects, packaging mainly means arranging files and documentation in a clear, reproducible structure and providing simple installation instructions. This helps classmates and teachers import and test your library without confusion or errors.

Basic package structure
A minimal package for a small library contains a folder named after the library, module files inside it, and an __init__ file that marks the folder as a package and optionally defines what should be exported. Include a README that explains purpose, usage, and any installation steps. Adding a version.txt or including a version string in the code helps users know which release they have.

Preparing files for sharing
For classroom distribution, compress the package folder into a zip archive and include it with your submission. Provide simple installation or usage steps in the README: for example, instruct students to unzip the folder in the project directory or add the folder path to the environment's module search path. Keep third-party dependencies minimal and list any required libraries in a plain text file (requirements.txt) with specific versions where necessary.

Testing the packaged library
Before sharing, test the library in a fresh folder or environment to ensure imports work without relying on developer-specific paths. Run the example scripts that demonstrate typical usage to verify everything functions as expected. If possible, ask a classmate to try installing and running your package to catch any missing steps.

Versioning and changelog
Assign a version number to each released package (for example, 1.0.0). Maintain a short changelog that documents major changes and fixes. When you update the package in a way that breaks previous behaviour, increment the major version and note breaking changes so users can adapt.

Distribution methods
For school, simple sharing by zip file or via a classroom platform is adequate. Advanced distribution via a package index is not required for Class 10 but keep in mind that good packaging practices scale to larger projects.

Licensing and attribution
Include a simple licence file indicating how others may use your code. For educational sharing, a permissive note allowing reuse for learning is usually enough. Also include attribution for any third-party code you modified or used.

Useful modules to learn
Certain standard library modules are especially helpful for school projects. File I/O modules let you open, read and write files. The csv module helps parse and write comma-separated values. json helps store structured data in a widely supported format. datetime handles dates and times, and math and random provide numerical utilities. Collections or similar modules offer specialised containers like queues, deques, and default dictionaries that simplify tasks.

How each module helps

• File I/O: basic reading/writing of text files for input and output.
• csv: read student marks in table form and write summaries.
• json: save nested data like student profiles or settings.
• datetime: compute age, durations, and format timestamps consistently.
• math/random: compute averages, round values, or generate sample test data.
• collections: efficient data structures for queues or groupings.

Combining modules in projects
Real assignments often require combining modules: for example, read input with csv, use datetime to parse date strings, aggregate scores with collections, and write results back with csv or json. Understanding how these modules interoperate helps design clear data flows in your program.

Performance considerations
Standard library modules are designed for common cases; for very large datasets, process data in streams instead of loading everything into memory. Use buffered reading and write incrementally to keep memory usage low. When performance matters, choose appropriate data structures (for example, use deque for frequent insertions/removals at both ends).

Practical examples
A marks processing program could use csv to read marks.csv, compute averages using math functions, sort students by average and write a summary CSV. An attendance tracker could store daily records in JSON and use datetime to compute total presence days and generate reports.

Choosing modules for reliability
Prefer standard modules because they are present in most environments used by schools. If a third-party module is necessary, include clear instructions and a requirements list. Always document which modules you used and why, so reviewers know how to run your program.

What wrappers and adapters do
Wrappers and adapters are small pieces of code that sit between your application and a library. They translate your program's needs into calls the library understands, simplify complex APIs, add validation, and centralise error handling. A wrapper helps keep the rest of your code independent from a specific library, making it easier to replace or update the library later.

Design goals for a wrapper

• Provide a simpler, stable interface tailored to your program's needs.
• Validate inputs and convert them into the formats a library expects.
• Catch and translate low-level exceptions into clearer, higher-level messages for your application.
• Offer default behaviours so callers do not repeat common checks.

When to use a wrapper
Use wrappers when the library API is complex, inconsistent, or when you need to unify different libraries to a single interface. Wrappers are useful if you access the same functionality from multiple programs or when you expect the library to change—only the wrapper needs modification, keeping the rest of the code stable.

Examples of adapter patterns

• Parameter translation: convert date strings in various formats into a single date object before calling the library.
• Result normalization: convert library-specific return types into simple Python types used across your program.
• Fallback behaviour: try a primary method and use an alternative on failure, hiding complexity from callers.

Simple wrapper implementation
A wrapper class might accept high-level inputs in its constructor, perform validation, and internally call library methods. Public methods expose simplified operations. Keep the wrapper small and focused: if it grows large, split it into multiple helper classes. Document the wrapper's behaviour and the exceptions it raises.

Testing wrappers
Test wrappers by mocking library calls where possible or by using small controlled inputs. Ensure that input validation and exception translation work as documented. Wrappers also make tests easier because they reduce the number of places where library-specific behaviour appears.

Benefits
Wrappers improve code clarity, make maintenance safer, and reduce the impact of library changes on the rest of your program—valuable qualities in both learning and assessment contexts.

Why dependency tracking matters
When your code relies on external libraries, specifying which versions you used ensures that others can reproduce your environment and get the same behaviour. Different versions may change function names, parameters or behaviour, causing programs to break if not managed carefully. For Class 10 projects, simple, clear dependency notes are sufficient to avoid most issues.

Recording dependencies
Record the names and exact versions of third-party libraries in a plain text file (for example requirements.txt) or in a short section of your README. Use the equality operator to pin versions (library==1.2.3) so that others install the tested release. If you use only standard libraries, note this explicitly so reviewers know no extra installation is needed.

Using virtual environments
Virtual environments isolate project dependencies from the global system. For development, use a virtual environment and record its activation steps in your README. While virtual environments may be advanced for some students, understanding that they create a predictable environment is useful and recommended for sharing reproducible projects.

Updating dependencies
Before updating a library, run your tests to ensure nothing breaks. When a library update introduces breaking changes, either update your code shortly afterward and increase your project's version, or keep the older pinned version in requirements.txt. Maintain a changelog that records major dependency updates so users know what changed.

Handling conflicts
If two libraries require different versions of a shared dependency, the safest path is to avoid one of the conflicting libraries, run them in separate environments, or choose alternatives with compatible versions. For class projects, minimize external dependencies to avoid complex conflicts.

Sharing instructions
Include simple installation commands and the exact commands used to create any environment in your README. For example, list pip install -r requirements.txt and the versions used. This helps teachers and peers set up your project quickly and test it reliably.

What a licence does
A software licence defines how code may be used, modified and shared. Different licences impose different rules: some allow free reuse with attribution, others require derivative works to use the same licence, and some restrict commercial use. Understanding licences is important even for classroom projects because it teaches legal and ethical use of other people's work.

Common licence types
Permissive licences (like MIT or BSD) allow copying, modification and redistribution with minimal requirements, usually an attribution notice. Copyleft licences (like GPL) require that derivative works be distributed under the same licence, which may affect sharing. Proprietary licences restrict reuse and may require payment or explicit permission.

How to check a library's licence
Most libraries include a LICENSE file in their repository or list licence details on their project page. Check this before including a library in your project. If a library's licence is unclear, avoid using it or ask a teacher for guidance. For class sharing, choose libraries with permissive licences to avoid complications.

Attribution and credit
Give credit to authors of libraries you use by listing them in your README and by including their required licence notices. If you adapt or copy portions of code, include a comment noting the source and the licence under which it was used. This shows good academic practice and respect for authors' rights.

Ethical considerations
Avoid copying code without permission. When using online examples, follow licence rules and give credit. Do not present substantial parts of others' work as your own. When in doubt, ask a teacher or reference the project's licence information directly.

Licensing for your own code
If you plan to share your library beyond class, include a short licence file stating how others may use it. For classroom sharing, a permissive licence or a note allowing reuse for educational purposes is typically sufficient. Clear licensing removes ambiguity and encourages lawful reuse.

Overview of the project
This final topic guides you through designing, implementing and sharing a small reusable library as a class project. The goal is to apply the unit's ideas: write clear classes, document them, test them and package them for others to use. A suitable idea is a student records manager that reads and writes student data, computes grades, and exports reports.

Step 1 — Decide scope
List the core features you need. For a student manager, features might include: create and store student records, compute average marks, find toppers, and export data as CSV or JSON. Keep the scope small and focused to finish within the project time.

Step 2 — Design classes and modules
Sketch classes: Student (attributes: name, id, marks; methods: compute_average, grade), RecordManager (load, save, add, remove, list). Place classes in logical modules: data_models.py for Student and manager.py for RecordManager. Add a small utils.py for file helpers. Document each class with docstrings describing parameters, returns and exceptions.

Step 3 — Implement and test
Write small units of functionality and test as you go. Create unit tests for compute_average with normal inputs and edge cases (empty marks list). Provide example scripts that demonstrate typical usage: create records, compute class average and write a CSV. Use exception handling to manage missing files or malformed data gracefully.

Step 4 — Create a simple wrapper if needed
If the file format or API you use is complex, write a thin wrapper that hides complexity and presents a stable interface for the rest of the program. For example, CSVWrapper can ensure rows are returned as dictionaries with sane defaults for missing fields.

Step 5 — Document and package
Prepare a README with installation or placement instructions, list any dependencies and include sample commands. Assign a version number and keep a changelog of major updates. Package the folder with an __init__ if you have multiple modules and compress it for sharing.

Step 6 — Share and validate
Ask a classmate to unzip and run your example scripts following your README. Fix any issues they face and update the documentation. Include a short note about the licence and attribution if you used external code.

Learning outcomes
Completing this project demonstrates the full cycle of library design: clear interfaces, documentation, testing and sharing. It builds practical skills in modular programming and prepares you for larger projects.