edsl 0.1.38.dev1__py3-none-any.whl → 0.1.38.dev2__py3-none-any.whl

edsl/Base.py

@@ -256,10 +256,10 @@ class Base(
 
         if not isinstance(other, self.__class__):
             return False
-        if "sort" in inspect.signature(self._to_dict).parameters:
-            return self._to_dict(sort=True) == other._to_dict(sort=True)
+        if "sort" in inspect.signature(self.to_dict).parameters:
+            return self.to_dict(sort=True) == other.to_dict(sort=True)
         else:
-            return self._to_dict() == other._to_dict()
+            return self.to_dict() == other.to_dict()
 
     @abstractmethod
     def example():

edsl/BaseDiff.py

@@ -25,7 +25,7 @@ class DummyObject:
     def __init__(self, object_dict):
         self.object_dict = object_dict
 
-    def _to_dict(self):
+    def to_dict(self):
         return self.object_dict
 
 
@@ -38,12 +38,12 @@ class BaseDiff:
         self.obj1 = obj1
         self.obj2 = obj2
 
-        if "sort" in inspect.signature(obj1._to_dict).parameters:
-            self._dict1 = obj1._to_dict(sort=True)
-            self._dict2 = obj2._to_dict(sort=True)
+        if "sort" in inspect.signature(obj1.to_dict).parameters:
+            self._dict1 = obj1.to_dict(sort=True)
+            self._dict2 = obj2.to_dict(sort=True)
         else:
-            self._dict1 = obj1._to_dict()
-            self._dict2 = obj2._to_dict()
+            self._dict1 = obj1.to_dict()
+            self._dict2 = obj2.to_dict()
         self._obj_class = type(obj1)
 
         self.added = added
@@ -139,7 +139,7 @@ class BaseDiff:
     def apply(self, obj: Any):
         """Apply the diff to the object."""
 
-        new_obj_dict = obj._to_dict()
+        new_obj_dict = obj.to_dict()
         for k, v in self.added.items():
             new_obj_dict[k] = v
         for k in self.removed.keys():

edsl/__init__.py

@@ -41,7 +41,8 @@ from edsl.shared import shared_globals
 from edsl.jobs.Jobs import Jobs
 from edsl.notebooks.Notebook import Notebook
 from edsl.study.Study import Study
-from edsl.conjure.Conjure import Conjure
+
+# from edsl.conjure.Conjure import Conjure
 from edsl.coop.coop import Coop
 
 from edsl.surveys.instructions.Instruction import Instruction

edsl/__version__.py

@@ -1 +1 @@
-__version__ = "0.1.38.dev1"
+__version__ = "0.1.38.dev2"

edsl/agents/Agent.py

@@ -669,9 +669,9 @@ class Agent(Base):
             if dynamic_traits_func:
                 func = inspect.getsource(dynamic_traits_func)
                 raw_data["dynamic_traits_function_source_code"] = func
-                raw_data[
-                    "dynamic_traits_function_name"
-                ] = self.dynamic_traits_function_name
+                raw_data["dynamic_traits_function_name"] = (
+                    self.dynamic_traits_function_name
+                )
         if hasattr(self, "answer_question_directly"):
             raw_data.pop(
                 "answer_question_directly", None
@@ -685,23 +685,19 @@ class Agent(Base):
                 raw_data["answer_question_directly_source_code"] = inspect.getsource(
                     answer_question_directly_func
                 )
-                raw_data[
-                    "answer_question_directly_function_name"
-                ] = self.answer_question_directly_function_name
+                raw_data["answer_question_directly_function_name"] = (
+                    self.answer_question_directly_function_name
+                )
 
         return raw_data
 
     def __hash__(self) -> int:
         from edsl.utilities.utilities import dict_hash
 
-        return dict_hash(self._to_dict())
-
-    def _to_dict(self) -> dict[str, Union[dict, bool]]:
-        """Serialize to a dictionary without EDSL info"""
-        return self.data
+        return dict_hash(self.to_dict(add_edsl_version=False))
 
-    @add_edsl_version
-    def to_dict(self) -> dict[str, Union[dict, bool]]:
+    # @add_edsl_version
+    def to_dict(self, add_edsl_version=True) -> dict[str, Union[dict, bool]]:
         """Serialize to a dictionary with EDSL info.
 
         Example usage:
@@ -710,7 +706,14 @@ class Agent(Base):
         >>> a.to_dict()
         {'name': 'Steve', 'traits': {'age': 10, 'hair': 'brown', 'height': 5.5}, 'edsl_version': '...', 'edsl_class_name': 'Agent'}
         """
-        return self._to_dict()
+        d = copy.deepcopy(self.data)
+        if add_edsl_version:
+            from edsl import __version__
+
+            d["edsl_version"] = __version__
+            d["edsl_class_name"] = self.__class__.__name__
+
+        return d
 
     @classmethod
     @remove_edsl_version

edsl/agents/AgentList.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 import csv
 import json
 from collections import UserList
-from typing import Any, List, Optional, Union
+from typing import Any, List, Optional, Union, TYPE_CHECKING
 from rich import print_json
 from rich.table import Table
 from simpleeval import EvalWithCompoundTypes
@@ -23,6 +23,11 @@ from edsl.utilities.decorators import add_edsl_version, remove_edsl_version
 
 from collections.abc import Iterable
 
+from edsl.exceptions.agents import AgentListError
+
+if TYPE_CHECKING:
+    from edsl.scenarios.ScenarioList import ScenarioList
+
 
 def is_iterable(obj):
     return isinstance(obj, Iterable)
@@ -113,7 +118,7 @@ class AgentList(UserList, Base):
             ]
         except Exception as e:
             print(f"Exception:{e}")
-            raise Exception(f"Error in filter. Exception:{e}")
+            raise AgentListError(f"Error in filter. Exception:{e}")
 
         return AgentList(new_data)
 
@@ -199,7 +204,8 @@ class AgentList(UserList, Base):
         >>> al.add_trait('new_trait', [1, 2, 3])
         Traceback (most recent call last):
         ...
-        ValueError: The passed values have to be the same length as the agent list.
+        edsl.exceptions.agents.AgentListError: The passed values have to be the same length as the agent list.
+        ...
         """
         if not is_iterable(values):
             value = values
@@ -208,7 +214,7 @@ class AgentList(UserList, Base):
             return self
 
         if len(values) != len(self):
-            raise ValueError(
+            raise AgentListError(
                 "The passed values have to be the same length as the agent list."
             )
         for agent, value in zip(self.data, values):
@@ -228,33 +234,39 @@ class AgentList(UserList, Base):
     def __hash__(self) -> int:
         from edsl.utilities.utilities import dict_hash
 
-        data = self.to_dict()
-        # data['agent_list'] = sorted(data['agent_list'], key=lambda x: dict_hash(x)
-        return dict_hash(self._to_dict(sorted=True))
+        return dict_hash(self.to_dict(add_edsl_version=False, sorted=True))
 
-    def _to_dict(self, sorted=False):
+    def to_dict(self, sorted=False, add_edsl_version=True):
         if sorted:
             data = self.data[:]
             data.sort(key=lambda x: hash(x))
         else:
             data = self.data
 
-        return {"agent_list": [agent.to_dict() for agent in data]}
+        d = {
+            "agent_list": [
+                agent.to_dict(add_edsl_version=add_edsl_version) for agent in data
+            ]
+        }
+        if add_edsl_version:
+            from edsl import __version__
 
-    def __eq__(self, other: AgentList) -> bool:
-        return self._to_dict(sorted=True) == other._to_dict(sorted=True)
+            d["edsl_version"] = __version__
+            d["edsl_class_name"] = "AgentList"
+
+        return d
 
-    @add_edsl_version
-    def to_dict(self):
-        """Return dictionary of AgentList to serialization."""
-        return self._to_dict()
+    def __eq__(self, other: AgentList) -> bool:
+        return self.to_dict(sorted=True, add_edsl_version=False) == other.to_dict(
+            sorted=True, add_edsl_version=False
+        )
 
     def __repr__(self):
         return f"AgentList({self.data})"
 
     def print(self, format: Optional[str] = None):
         """Print the AgentList."""
-        print_json(json.dumps(self._to_dict()))
+        print_json(json.dumps(self.to_dict(add_edsl_version=False)))
 
     def _repr_html_(self):
         """Return an HTML representation of the AgentList."""
@@ -262,7 +274,7 @@ class AgentList(UserList, Base):
 
         return data_to_html(self.to_dict()["agent_list"])
 
-    def to_scenario_list(self) -> "ScenarioList":
+    def to_scenario_list(self) -> ScenarioList:
         """Return a list of scenarios."""
         from edsl.scenarios.ScenarioList import ScenarioList
         from edsl.scenarios.Scenario import Scenario

edsl/auto/SurveyCreatorPipeline.py

@@ -15,7 +15,7 @@ from edsl.surveys.Survey import Survey
 from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice
 from edsl.questions.QuestionFreeText import QuestionFreeText
 from edsl.auto.utilities import gen_pipeline
-from edsl.conjure.naming_utilities import sanitize_string
+from edsl.utilities.naming_utilities import sanitize_string
 
 
 m = Model()

edsl/auto/utilities.py

@@ -2,7 +2,7 @@ from textwrap import dedent
 import random
 from typing import List, TypeVar, Generator, Optional
 from edsl.auto.StageBase import StageBase
-from edsl.conjure.naming_utilities import sanitize_string
+from edsl.utilities.naming_utilities import sanitize_string
 from edsl import Agent, Survey, Model, Cache, AgentList
 from edsl import QuestionFreeText, Scenario
 from edsl import QuestionMultipleChoice, Scenario, Agent, ScenarioList

edsl/base/Base.py

@@ -229,26 +229,16 @@ class Base(
 
         return data_to_html(self.to_dict())
 
-    # def html(self):
-    #     html_string = self._repr_html_()
-    #     import tempfile
-    #     import webbrowser
-
-    #     with tempfile.NamedTemporaryFile("w", delete=False, suffix=".html") as f:
-    #         # print("Writing HTML to", f.name)
-    #         f.write(html_string)
-    #         webbrowser.open(f.name)
-
     def __eq__(self, other):
         """Return whether two objects are equal."""
         import inspect
 
         if not isinstance(other, self.__class__):
             return False
-        if "sort" in inspect.signature(self._to_dict).parameters:
-            return self._to_dict(sort=True) == other._to_dict(sort=True)
+        if "sort" in inspect.signature(self.to_dict).parameters:
+            return self.to_dict(sort=True) == other.to_dict(sort=True)
         else:
-            return self._to_dict() == other._to_dict()
+            return self.to_dict() == other.to_dict()
 
     @abstractmethod
     def example():

edsl/coop/coop.py

@@ -42,6 +42,9 @@ class Coop:
             self.api_url = self.url
         self._edsl_version = edsl.__version__
 
+    def get_progress_bar_url(self):
+        return f"{CONFIG.EXPECTED_PARROT_URL}"
+
     ################
     # BASIC METHODS
     ################

edsl/data/Cache.py

@@ -11,7 +11,8 @@ from typing import Optional, Union
 from edsl.Base import Base
 from edsl.data.CacheEntry import CacheEntry
 from edsl.utilities.utilities import dict_hash
-from edsl.utilities.decorators import add_edsl_version, remove_edsl_version
+from edsl.utilities.decorators import remove_edsl_version
+from edsl.exceptions.cache import CacheError
 
 
 class Cache(Base):
@@ -58,7 +59,7 @@ class Cache(Base):
 
         self.filename = filename
         if filename and data:
-            raise ValueError("Cannot provide both filename and data")
+            raise CacheError("Cannot provide both filename and data")
         if filename is None and data is None:
             data = {}
         if data is not None:
@@ -76,7 +77,7 @@ class Cache(Base):
                 if os.path.exists(filename):
                     self.add_from_sqlite(filename)
             else:
-                raise ValueError("Invalid file extension. Must be .jsonl or .db")
+                raise CacheError("Invalid file extension. Must be .jsonl or .db")
 
         self._perform_checks()
 
@@ -116,7 +117,7 @@ class Cache(Base):
         from edsl.data.CacheEntry import CacheEntry
 
         if any(not isinstance(value, CacheEntry) for value in self.data.values()):
-            raise Exception("Not all values are CacheEntry instances")
+            raise CacheError("Not all values are CacheEntry instances")
         if self.method is not None:
             warnings.warn("Argument `method` is deprecated", DeprecationWarning)
 
@@ -227,9 +228,9 @@ class Cache(Base):
         for key, value in new_data.items():
             if key in self.data:
                 if value != self.data[key]:
-                    raise Exception("Mismatch in values")
+                    raise CacheError("Mismatch in values")
             if not isinstance(value, CacheEntry):
-                raise Exception(f"Wrong type - the observed type is {type(value)}")
+                raise CacheError(f"Wrong type - the observed type is {type(value)}")
 
         self.new_entries.update(new_data)
         if write_now:
@@ -338,7 +339,7 @@ class Cache(Base):
         elif filename.endswith(".db"):
             self.write_sqlite_db(filename)
         else:
-            raise ValueError("Invalid file extension. Must be .jsonl or .db")
+            raise CacheError("Invalid file extension. Must be .jsonl or .db")
 
     def write_jsonl(self, filename: str) -> None:
         """
@@ -396,15 +397,17 @@ class Cache(Base):
     ####################
     def __hash__(self):
         """Return the hash of the Cache."""
-        return dict_hash(self._to_dict())
+        return dict_hash(self.to_dict(add_edsl_version=False))
 
-    def _to_dict(self) -> dict:
-        return {k: v.to_dict() for k, v in self.data.items()}
+    def to_dict(self, add_edsl_version=True) -> dict:
+        d = {k: v.to_dict() for k, v in self.data.items()}
+        if add_edsl_version:
+            from edsl import __version__
+
+            d["edsl_version"] = __version__
+            d["edsl_class_name"] = "Cache"
 
-    @add_edsl_version
-    def to_dict(self) -> dict:
-        """Return the Cache as a dictionary."""
-        return self._to_dict()
+        return d
 
     def _repr_html_(self):
         from edsl.utilities.utilities import data_to_html
@@ -438,7 +441,7 @@ class Cache(Base):
         Combine two caches.
         """
         if not isinstance(other, Cache):
-            raise ValueError("Can only add two caches together")
+            raise CacheError("Can only add two caches together")
         self.data.update(other.data)
         return self
 

edsl/exceptions/agents.py

@@ -1,6 +1,10 @@
 from edsl.exceptions.BaseException import BaseException
 
 
+class AgentListError(BaseException):
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html#agent-lists"
+
+
 class AgentErrors(BaseException):
     relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html"
 

edsl/exceptions/cache.py

@@ -0,0 +1,5 @@
+from edsl.exceptions.BaseException import BaseException
+
+
+class CacheError(BaseException):
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/agents.html#agent-lists"

edsl/jobs/Jobs.py

@@ -641,7 +641,7 @@ class Jobs(Base):
         """
         from edsl.utilities.utilities import dict_hash
 
-        return dict_hash(self._to_dict())
+        return dict_hash(self.to_dict(add_edsl_version=False))
 
     def _output(self, message) -> None:
         """Check if a Job is verbose. If so, print the message."""
@@ -1188,18 +1188,29 @@ class Jobs(Base):
     # Serialization methods
     #######################
 
-    def _to_dict(self):
-        return {
-            "survey": self.survey._to_dict(),
-            "agents": [agent._to_dict() for agent in self.agents],
-            "models": [model._to_dict() for model in self.models],
-            "scenarios": [scenario._to_dict() for scenario in self.scenarios],
+    def to_dict(self, add_edsl_version=True):
+        d = {
+            "survey": self.survey.to_dict(add_edsl_version=add_edsl_version),
+            "agents": [
+                agent.to_dict(add_edsl_version=add_edsl_version)
+                for agent in self.agents
+            ],
+            "models": [
+                model.to_dict(add_edsl_version=add_edsl_version)
+                for model in self.models
+            ],
+            "scenarios": [
+                scenario.to_dict(add_edsl_version=add_edsl_version)
+                for scenario in self.scenarios
+            ],
         }
+        if add_edsl_version:
+            from edsl import __version__
+
+            d["edsl_version"] = __version__
+            d["edsl_class_name"] = "Jobs"
 
-    @add_edsl_version
-    def to_dict(self) -> dict:
-        """Convert the Jobs instance to a dictionary."""
-        return self._to_dict()
+        return d
 
     @classmethod
     @remove_edsl_version

edsl/jobs/buckets/TokenBucket.py

@@ -220,6 +220,9 @@ class TokenBucket:
 
         elapsed_time = now - start_time
 
+        if elapsed_time == 0:
+            return self.num_released / 0.001
+
         return (self.num_released / elapsed_time) * 60
 
         # # Filter log entries within the time window

edsl/jobs/interviews/Interview.py

@@ -110,9 +110,9 @@ class Interview:
         self.debug = debug
         self.iteration = iteration
         self.cache = cache
-        self.answers: dict[
-            str, str
-        ] = Answers()  # will get filled in as interview progresses
+        self.answers: dict[str, str] = (
+            Answers()
+        )  # will get filled in as interview progresses
         self.sidecar_model = sidecar_model
 
         # Trackers
@@ -143,9 +143,9 @@ class Interview:
         The keys are the question names; the values are the lists of status log changes for each task.
         """
         for task_creator in self.task_creators.values():
-            self._task_status_log_dict[
-                task_creator.question.question_name
-            ] = task_creator.status_log
+            self._task_status_log_dict[task_creator.question.question_name] = (
+                task_creator.status_log
+            )
         return self._task_status_log_dict
 
     @property
@@ -159,7 +159,7 @@ class Interview:
         return self.task_creators.interview_status
 
     # region: Serialization
-    def _to_dict(self, include_exceptions=True) -> dict[str, Any]:
+    def to_dict(self, include_exceptions=True, add_edsl_version=True) -> dict[str, Any]:
         """Return a dictionary representation of the Interview instance.
         This is just for hashing purposes.
 
@@ -168,10 +168,10 @@ class Interview:
         1217840301076717434
         """
         d = {
-            "agent": self.agent._to_dict(),
-            "survey": self.survey._to_dict(),
-            "scenario": self.scenario._to_dict(),
-            "model": self.model._to_dict(),
+            "agent": self.agent.to_dict(add_edsl_version=add_edsl_version),
+            "survey": self.survey.to_dict(add_edsl_version=add_edsl_version),
+            "scenario": self.scenario.to_dict(add_edsl_version=add_edsl_version),
+            "model": self.model.to_dict(add_edsl_version=add_edsl_version),
             "iteration": self.iteration,
             "exceptions": {},
         }
@@ -202,11 +202,11 @@ class Interview:
     def __hash__(self) -> int:
         from edsl.utilities.utilities import dict_hash
 
-        return dict_hash(self._to_dict(include_exceptions=False))
+        return dict_hash(self.to_dict(include_exceptions=False, add_edsl_version=False))
 
     def __eq__(self, other: "Interview") -> bool:
         """
-        >>> from edsl.jobs.interviews.Interview import Interview; i = Interview.example(); d = i._to_dict(); i2 = Interview.from_dict(d); i == i2
+        >>> from edsl.jobs.interviews.Interview import Interview; i = Interview.example(); d = i.to_dict(); i2 = Interview.from_dict(d); i == i2
         True
         """
         return hash(self) == hash(other)
@@ -486,11 +486,11 @@ class Interview:
         """
         current_question_index: int = self.to_index[current_question.question_name]
 
-        next_question: Union[
-            int, EndOfSurvey
-        ] = self.survey.rule_collection.next_question(
-            q_now=current_question_index,
-            answers=self.answers | self.scenario | self.agent["traits"],
+        next_question: Union[int, EndOfSurvey] = (
+            self.survey.rule_collection.next_question(
+                q_now=current_question_index,
+                answers=self.answers | self.scenario | self.agent["traits"],
+            )
         )
 
         next_question_index = next_question.next_q

edsl/jobs/runners/JobsRunnerAsyncio.py

@@ -2,13 +2,13 @@ from __future__ import annotations
 import time
 import asyncio
 import threading
-from typing import Coroutine, List, AsyncGenerator, Optional, Union, Generator
-from contextlib import contextmanager
+import warnings
+from typing import Coroutine, List, AsyncGenerator, Optional, Union, Generator, Type
 from collections import UserList
 
 from edsl.results.Results import Results
 from edsl.jobs.interviews.Interview import Interview
-from edsl.jobs.runners.JobsRunnerStatus import JobsRunnerStatus
+from edsl.jobs.runners.JobsRunnerStatus import JobsRunnerStatus, JobsRunnerStatusBase
 
 from edsl.jobs.tasks.TaskHistory import TaskHistory
 from edsl.jobs.buckets.BucketCollection import BucketCollection
@@ -41,6 +41,7 @@ class JobsRunnerAsyncio:
         self.interviews: List["Interview"] = jobs.interviews()
         self.bucket_collection: "BucketCollection" = jobs.bucket_collection
         self.total_interviews: List["Interview"] = []
+        self._initialized = threading.Event()
 
     async def run_async_generator(
         self,
@@ -69,6 +70,8 @@ class JobsRunnerAsyncio:
                 self._populate_total_interviews(n=n)
             )  # Populate self.total_interviews before creating tasks
 
+        self._initialized.set()  # Signal that we're ready
+
         for interview in self.total_interviews:
             interviewing_task = self._build_interview_task(
                 interview=interview,
@@ -165,20 +168,20 @@ class JobsRunnerAsyncio:
 
         prompt_dictionary = {}
         for answer_key_name in answer_key_names:
-            prompt_dictionary[
-                answer_key_name + "_user_prompt"
-            ] = question_name_to_prompts[answer_key_name]["user_prompt"]
-            prompt_dictionary[
-                answer_key_name + "_system_prompt"
-            ] = question_name_to_prompts[answer_key_name]["system_prompt"]
+            prompt_dictionary[answer_key_name + "_user_prompt"] = (
+                question_name_to_prompts[answer_key_name]["user_prompt"]
+            )
+            prompt_dictionary[answer_key_name + "_system_prompt"] = (
+                question_name_to_prompts[answer_key_name]["system_prompt"]
+            )
 
         raw_model_results_dictionary = {}
         cache_used_dictionary = {}
         for result in valid_results:
             question_name = result.question_name
-            raw_model_results_dictionary[
-                question_name + "_raw_model_response"
-            ] = result.raw_model_response
+            raw_model_results_dictionary[question_name + "_raw_model_response"] = (
+                result.raw_model_response
+            )
             raw_model_results_dictionary[question_name + "_cost"] = result.cost
             one_use_buys = (
                 "NA"
@@ -275,6 +278,7 @@ class JobsRunnerAsyncio:
         stop_on_exception: bool = False,
         progress_bar: bool = False,
         sidecar_model: Optional[LanguageModel] = None,
+        jobs_runner_status: Optional[Type[JobsRunnerStatusBase]] = None,
         print_exceptions: bool = True,
         raise_validation_errors: bool = False,
     ) -> "Coroutine":
@@ -286,7 +290,21 @@ class JobsRunnerAsyncio:
         self.cache = cache
         self.sidecar_model = sidecar_model
 
-        self.jobs_runner_status = JobsRunnerStatus(self, n=n)
+        from edsl.coop import Coop
+
+        coop = Coop()
+        endpoint_url = coop.get_progress_bar_url()
+
+        if jobs_runner_status is not None:
+            self.jobs_runner_status = jobs_runner_status(
+                self, n=n, endpoint_url=endpoint_url
+            )
+        else:
+            self.jobs_runner_status = JobsRunnerStatus(
+                self,
+                n=n,
+                endpoint_url=endpoint_url,
+            )
 
         stop_event = threading.Event()
 
@@ -306,11 +324,16 @@ class JobsRunnerAsyncio:
             """Runs the progress bar in a separate thread."""
             self.jobs_runner_status.update_progress(stop_event)
 
-        if progress_bar:
+        if progress_bar and self.jobs_runner_status.has_ep_api_key():
+            self.jobs_runner_status.setup()
             progress_thread = threading.Thread(
                 target=run_progress_bar, args=(stop_event,)
             )
             progress_thread.start()
+        elif progress_bar:
+            warnings.warn(
+                "You need an Expected Parrot API key to view job progress bars."
+            )
 
         exception_to_raise = None
         try:
@@ -325,7 +348,7 @@ class JobsRunnerAsyncio:
             stop_event.set()
         finally:
             stop_event.set()
-            if progress_bar:
+            if progress_bar and self.jobs_runner_status.has_ep_api_key():
                 # self.jobs_runner_status.stop_event.set()
                 if progress_thread:
                     progress_thread.join()